Quellcode Kommentieren

[franktron]

Kennt jemand eine Erweiterung für Delphi (XE2) die Automatich ein Kommentar für eine Procedure erstellt

[himitsu]

Wie AUTOMATISCH?
Und wenn wo soll der Text her kommen?

Documentaion Insight
Codevorlagen
...

[ChristianG]

Die Kommentare musst du selbst schreiben. Oder du schreibst ein Programm, was künstliche Intelligenz hat, um deine Logik zu erkennen. Das sollte nicht böse gemeint sein, sondern eher zeigen, dass solch ein Programm sehr komplex ist und möglicherweise noch nicht realisierbar. Also einfach weiter mit // kommentieren :) .
Oder möglicherweise habe ich die Frage nicht verstanden :/.
Mit freundlichen Grüßen

[franktron]

Ich hatte mal eine Erweiterung die das machte

Bsp.
//*******************************
//Procedurenname Param1 Param1
//Erstallt am xx.xx.xxxx von Frank
//Geändert am xx.xx.xxxx von Frank
//***********************************

[Bernhard Geyer]

Es geht vermutlich eher um die Textvorlagen das das "Drumherum" um den eigentlichen Kommentar automatisch eingefügt wird.
Also Eingabe von /// und dann soll die IDE automatisch die Parameter ergänzen so das man wirklich nur den eigenen Beschreibungstext eingeben muss.

[bernau]

Zitat:

Zitat von franktron (Beitrag 1267504)

Ich hatte mal eine Erweiterung die das machte

Bsp.
//*******************************
//Procedurenname Param1 Param1
//Erstallt am xx.xx.xxxx von Frank
//Geändert am xx.xx.xxxx von Frank
//***********************************

GExperts kann so etwas. Nutze ich permanent.

[franktron]

Zitat:

Zitat von bernau (Beitrag 1267507)

Zitat:

Zitat von franktron (Beitrag 1267504)

Ich hatte mal eine Erweiterung die das machte

Bsp.
//*******************************
//Procedurenname Param1 Param1
//Erstallt am xx.xx.xxxx von Frank
//Geändert am xx.xx.xxxx von Frank
//***********************************

GExperts kann so etwas. Nutze ich permanent.

Wo ? ich hab den

[bernau]

Menü->GExperts->Editor Experts->Expand Macro Templates

Oder Shift-Alt-T

Dann aus der Liste "Procedure Header" auswählen. Kannst du natürlich anpassen.

[sx2008]

Also bei uns in der Abteilung war das auch mal schwer in Mode *grundsätzlich* vor jede Funktion/Procedure/Methode einen Kommentarblock zu setzen.
Aber wenn man mal darüber nachdenkt, kommt man drauf dass das eigentlich ziemlich dumm ist.
Denn meistens steht im Kommentar nicht mehr als in der Funktion selber.
Wann eine Funktion erstellt und geändert wurde ist relativ uninteressant werden man eine Versionsverwaltung verwendet.
Und wenn man keine Versionsverwaltung hat dann wird's aber höchste Eisenbahn.

Die Nachteile der Zwangskommentare sind:
* Zeitverschwendung durch Einfügen und Pflegen von Kommentaren die keinen Zusatznutzen bringen
* visuelles Störfeuer - je mehr Zeichen auf dem Bildschirm sind umso mehr Kapazität benötigt das menschliche Gehirn um Wichtiges von Unwichtigem zu trennen
* die Stellen die wirklich mal einen Kommentar haben fallen gar nicht auf weil überall Kommentare stehen
* anstatt darüber nachzudenken wie man die Funktionen sprechender machen könnte verlässt man sich auf nutzlose Kommentare die im Zweifelsfall doch eh falsch sind weil sich Funktionsname und/oder Parameter geändert haben

Meine Empfehlung:
vor wichtigen/komplizierten/erklärungsbedüftigen Funktionen schreibt man eine Kommentarezeile die kurz beschreibt was die Funktion macht.
Hier ein Beispiel:

Delphi-Quellcode:

// wandelt einen Speicherbereich in einen hexadezimalen String
function BufferToHexString(buffer:Pointer;size:Integer):AnsiString;
begin
   if not Assigned(buffer) or (size<=0) then
      Result := ''
   else
   begin
      SetLength(Result, size*2);
      BinToHex(PChar(buffer), PChar(Result), size);
   end;
end;

Wobei in obigem Beispiel der Funktionsname schon so sprechend ist dass man auf den Kommentar auch verzichten könnte.
Mehr als eine Zeile zu schreiben ist nicht verboten!

[mjustin]

Zitat:

Zitat von sx2008 (Beitrag 1267519)

Die Nachteile der Zwangskommentare sind:
* Zeitverschwendung durch Einfügen und Pflegen von Kommentaren die keinen Zusatznutzen bringen

Mein Lieblingsbeispiel für Kommentare ohne Zusatznutzen:

Delphi-Quellcode:

  TForm1 = class(TForm)
  private
    { Private declarations }
  public
    { Public declarations }
  end;

;)

[bernau]

Zitat:

Zitat von sx2008 (Beitrag 1267519)

Die Nachteile der Zwangskommentare sind:
* Zeitverschwendung durch Einfügen und Pflegen von Kommentaren die keinen Zusatznutzen bringen
* visuelles Störfeuer - je mehr Zeichen auf dem Bildschirm sind umso mehr Kapazität benötigt das menschliche Gehirn um Wichtiges von Unwichtigem zu trennen
* die Stellen die wirklich mal einen Kommentar haben fallen gar nicht auf weil überall Kommentare stehen
* anstatt darüber nachzudenken wie man die Funktionen sprechender machen könnte verlässt man sich auf nutzlose Kommentare die im Zweifelsfall doch eh falsch sind weil sich Funktionsname und/oder Parameter geändert haben

Visuelles Störfeuer: Ich finde es sehr angenehm, wenn zwischen Proceduren ein "erkennbarer Block" steht, der zwei Proceduren voneinander trennt.
Eine Schnelle Info, wann diese Procedure angelegt wurde finde ich auch sehr gut. Benutze zwar ein Versionscontrolsystem. Aber das würde unnötige klicks benötigen.
Kommentare stehen im Procedure-Header nur, wenn es tatsächlich etwas wichtiges zu beachten gibt.

[Dejan Vu]

Zitat:

Zitat von bernau (Beitrag 1267524)

Ich finde es sehr angenehm, wenn zwischen Proceduren ein "erkennbarer Block" steht, der zwei Proceduren voneinander trennt.

Da reicht dann aber ein '(****** ... ****)' o.ä. Wenn's denn sein muss (ich finds grauslig).

Wenn man eine Methode kommentieren muss, ist sie zu lang, hat einen falschen Namen oder beides. Nur wenn ich z.B. eine Gesetzesvorlage (oder eine Spec) explizit umsetze, oder eine mathematische Formel/Verfahren etwas komplexeren Ausmaßes, kommt ein kurzer Kommentar rein mit Quelle.

Kommentare sind böse und lügen. Einfach mal 'Clean Code' lesen, dann weiß man, was ich meine. sx2008 hat das meiste ja schon erklärt.

[p80286]

Kommentar immer da wo's notwendig ist. Z.B. Uppercase,Upcase,Ansiuppercase... sollten mit einem Kommentar versehen werden, damit man die Feinheiten nicht immer nachschlagen muß.

Gruß
K-H

[Sherlock]

Zitat:

Zitat von Dejan Vu (Beitrag 1267536)

Zitat:

Zitat von bernau (Beitrag 1267524)

Ich finde es sehr angenehm, wenn zwischen Proceduren ein "erkennbarer Block" steht, der zwei Proceduren voneinander trennt.

Da reicht dann aber ein '(****** ... ****)' o.ä. Wenn's denn sein muss (ich finds grauslig).

Wenn man eine Methode kommentieren muss, ist sie zu lang, hat einen falschen Namen oder beides. Nur wenn ich z.B. eine Gesetzesvorlage (oder eine Spec) explizit umsetze, oder eine mathematische Formel/Verfahren etwas komplexeren Ausmaßes, kommt ein kurzer Kommentar rein mit Quelle.

Kommentare sind böse und lügen. Einfach mal 'Clean Code' lesen, dann weiß man, was ich meine. sx2008 hat das meiste ja schon erklärt.

Das ist ein sehr weit verbreiteter und sehr alter Irrtum, der einfach zu wiederlegen ist.
Du gehst davon aus, Dein Code sei korrekt und lesbar, und bedürfe darum keines Kommentars. Das sind schon zwei sehr persönliche Ansichten, die meiner Meinung nach nichts bei der Entwicklung zu suchen haben. Wen Kommentare stören, der kann sie gerne wegfalten. Aber in den Code gehören nunmal zumindest Kommentare, die erklären, was zum Teufel der Schöpfer eigentlich mit folgender Methode vor hatte - mindestens. Und wenn der Methodenname einen ganzen Satz ergibt - was nun wirklich nicht der Realität entspicht. Dennoch gehört da ein Kommentar davor, der darlegt, was man da warum tun wollte. Ich habe das gerade erst letzte Woche erlebt, daß ein simpler Zweizeiler überhaupt nicht tat, was man an der Stelle erwartet hätte. Er war schlicht falsch. Wunderschön in sich, ja, denn kein störender Kommentar weit und breit, und die Methode hatte einen ganz toll sprechenden Namen. Aber was da passierte, entsprach so gar keiner Spezifikation und führte im folgenden zu massiven Problemen. Darum: Lieber zu viel Kommentare als zu wenig. Und bitte die Kommentare aktuell halten. Dann ist ja schon die halbe Doku fertig.

Sherlock

[Dejan Vu]

Zitat:

Zitat von Sherlock (Beitrag 1267541)

Du gehst davon aus, Dein Code sei korrekt und lesbar, und bedürfe darum keines Kommentars.

Nein. *Wir* gehen davon aus, das Team. Man muss schon professionell vorgehen, damit 'guter' Code auch gut ist. Und dazu gehört, das man die Scheuklappen abnimmt und den Code im Team reviewt. Ich mecker auch am Code meiner Kollegen rum, wenn die das nicht KISS-technisch und für mich verständlich umgesetzt haben.

Zitat:

Aber in den Code gehören nunmal zumindest Kommentare, die erklären, was zum Teufel der Schöpfer eigentlich mit folgender Methode vor hatte - mindestens.

Wieso? Sie ist doch selbsterklärend. Ich kommentiere doch nicht das offensichtliche. Das *ist* doch gerade die Krankheit.

Zitat:

Und wenn der Methodenname einen ganzen Satz ergibt - was nun wirklich nicht der Realität entspicht.

Dann ist die Methode zu komplex, gehört refaktorisiert und dann passt das auch mit dem Namen.

NIE NIE NIEMALS versuchen, mit Kommentaren den Code einer Methode zu erklären. Entweder ein geschulter Programmierer (kein Newbie, is klar) kann das lesen, oder ich muss mich ransetzen und das lesbar machen. Entweder durch Refaktorisierung oder eben (wer versteht schon die Syderberg-Shnayderman-Transformation im Rotationsgefubbel der 7.Querdimension?) durch einen knappen Kommentar mit Quelle. So halten wir das. Und wir sind alles alte Säcke mit 10-30 Jahren VerzweiflungProgrammiererfahrung.

Wir kommentieren allerdings auch Workarounds um VCL-Bugs, ist klar.

Zitat:

Darum: Lieber zu viel Kommentare als zu wenig. Und bitte die Kommentare aktuell halten. Dann ist ja schon die halbe Doku fertig.

Also 'zuviel' ist genauso falsch wie 'zu wenig'. Gerade richtig ist die Devise. Wenn deine beiden Codezeilen auch durch Refactoring nicht lesbarer werden (ich bezweifle das, aber z.B. bei komischen Formeln ist das so), dann wird erklärt, was das ist. Ansonsten kann ich dir jeden Code so umformulieren, das er verständlich wird (sofern Du programmieren kannst, bei meiner Frau klappt das nicht).

Und 'aktuell' ist die Doku eben per se nicht. Geht nicht, nirgens (außer bei Dir zu hause vielleicht). Weil Zeitdruck. Abgabe. Termin. Feierabend. Nächster Task oder Ticket. Anruf vom Teamleiter. Meeting. Frage vom Newbie oder Oldie. Usw. Wieviel Zeit da ins Land schreitet, die ganzen blödsinnigen, redundanten Kommentare nachzupflegen...Es ist Zeitverschwendung. Sagen zumindest die, mit denen ich bisher zusammengearbeitet habe.

Ich dokumentiere meinen Code jedenfalls nicht, sondern schreibe selbsterklärenden Code. Das ist die beste Kommentierung. Klar, das es auch Blödsinn gibt:

Delphi-Quellcode:

function GibMirDieMehrwertsteuer (einBetrag : TGeld) : TGeld;
Begin
  result := einBetrag * Einkommensteuersatz;
End;

Aber immerhin beinahe instantan ersichtlich, das der Programmierer einen schlechten Tag hatte.

Einzige Ausnahme unserer Regel (Redundanten Kommentar vermeiden): Die API. Auch wenn die Methode heißt 'ConvertRawBytesToHexString', muss eben darüber stehen: 'Converts raw bytes to a hex string'. Und dann klappts auch mit der Doku (weil die dann nämlich leer wäre und da fragt man sich auch? Wieso ist die Doku an dieser Stelle leer? Diese Schlampen!)

Delphi-Quellcode:

// Converts raw bytes to a hex String
// Parameter: inBytes - an Array of bytes to convert
//    returns the hex string
function TFoobar.ConvertRawBytesToHexString(inBytes : TByteArray)

Der redundantischste Kommentar der Welt (getoppt nur durch

Delphi-Quellcode:

 inc(i); // increase i

), aber (weil API Funktion) notwendig. Sonst nicht. Bei C# bekomme ich dadurch auch gleich meinen Live-Kommentar, wenn ich die Code-Completion anwerfe.


Da es Glaubenssache ist, einigen wir uns darauf, das Du Recht hast und ich auch und jeder sein Zeugs so macht, wie er es für richtig findet. Aber ich hoffe, wir sind uns darin einig, das selbsterklärender Code besser ist als ein Kommentar, der versucht, die durch Meth gestörten Gehirnwindungen des Programmierers zu erklären.

[mjustin]

Zitat:

Zitat von Dejan Vu (Beitrag 1267536)

Kommentare sind böse und lügen. Einfach mal 'Clean Code' lesen, dann weiß man, was ich meine.

Clean Code (bzw. Robert C Martin) sagt ja nicht, dass alle Kommentare schlecht sind, er nennt auch einige Fälle 'Guter' Kommentare. Auch ich würde keine API / Bibliothek / Komponente schreiben, in der "High-Level" Kommentare zu den öffentlichen Klassen und Methoden fehlen.

[Dejan Vu]

Das war sehr plakativ von mir. Ausnahmen (wie erwähnt) bestätigen die Regel.

[himitsu]

Zitat:

Zitat von Dejan Vu (Beitrag 1267543)

Und 'aktuell' ist die Doku eben per se nicht. Geht nicht, nirgens ...

Drum dokumentiere ich auch meinen Code aufgrund der Tatsache, daß der Code die Dokumentierung ist, werden dort eben auch die Interfaces sortiert/gruppiert.

Bei der Implementation hab ich die Sortierung ja aufgegeben, außer da, wo mehrere Funktionen versionsabhängig via Compilerschalter deaktiviert werden, welche dort in einem {$IF} landen, bzw. bei einem älteren größeren Projekt, wo ich die Implementation, der Übersicht wegen, in mehreren Regionen zusammengefasst hatte.


Aber ja, zuviele und vorallem "nutzlose" oder gar verwirrende Kommentare machen nichts besser ... eher das Gegenteil.


Und ich würde versuchen alle Funktionsbeschreibungen ins DocInsight zu legen, welches sich relativ problemlos um neue Felder erweitern lässt, damit man diese Kommentare auch in eine externe Dokumentation übernehmen kann, und vorallm damit sie im HelpInsight verfügbar sind.

[Sherlock]

Zitat:

Zitat von Dejan Vu (Beitrag 1267543)

Da es Glaubenssache ist, einigen wir uns darauf, das Du Recht hast und ich auch und jeder sein Zeugs so macht, wie er es für richtig findet. Aber ich hoffe, wir sind uns darin einig, das selbsterklärender Code besser ist als ein Kommentar, der versucht, die durch Meth gestörten Gehirnwindungen des Programmierers zu erklären.

Akzeptiert :thumb:

Das mit dem Meth muss ich mal bei Gelegenheit ausprobieren (lassen).

Was die aktualität der Doku angeht: Wir müssen unter anderem gemäß ISO 13485 entwickeln, da gibt es kein SW-Release ohne Doku.

Sherlock

[Dejan Vu]

Zitat:

Zitat von Sherlock (Beitrag 1267553)

Das mit dem Meth muss ich mal bei Gelegenheit ausprobieren (lassen).

Drogen und Programmieren passt irgendwie nicht. Entweder es wird viel zu kreativ und bunt, komplett verworren oder absolut krank. Hmm.

Zitat:

ISO 13485 entwickeln, da gibt es kein SW-Release ohne Doku.

Das betrifft doch nur die Doku und keine Quellcode-Kommentare, oder irre ich mich?

[Bernhard Geyer]

Zitat:

Zitat von Dejan Vu (Beitrag 1267556)

Zitat:

ISO 13485 entwickeln, da gibt es kein SW-Release ohne Doku.

Das betrifft doch nur die Doku und keine Quellcode-Kommentare, oder irre ich mich?

Die Frage ist eher ob primär sinnvolle Doku entsteht oder nur Doku der Doku wegen?
Manche Normen produzieren viel Papier ohne eine mehrwert zu haben.

[himitsu]

Zitat:

Zitat von Bernhard Geyer (Beitrag 1267557)

Die Frage ist eher ob primär sinnvolle Doku entsteht oder nur Doku der Doku wegen?

Die nichtvorhandenen Einträge in der Delphi-Doku, wo nur drin steht, daß hier noch nichts drin steht.

[Sherlock]

Zitat:

Zitat von Dejan Vu (Beitrag 1267556)

Zitat:

ISO 13485 entwickeln, da gibt es kein SW-Release ohne Doku.

Das betrifft doch nur die Doku und keine Quellcode-Kommentare, oder irre ich mich?

Wir ziehen Teile der Doku aus dem Quellcode.
Doku der Doku wegen ist ne brisante Frage. Da muss man sich mit einem TÜV-ler oder echten Qualitätsmanager drüber unterhalten. Am Ende macht es Sinn, aber es ist verdammt schwer sich dran zu halten.

Sherlock

[Bernhard Geyer]

Zitat:

Zitat von Sherlock (Beitrag 1267561)

Doku der Doku wegen ist ne brisante Frage. Da muss man sich mit einem TÜV-ler oder echten Qualitätsmanager drüber unterhalten. Am Ende macht es Sinn, aber es ist verdammt schwer sich dran zu halten.

So wie tausende Seiten Pflichten/Lastenheft die jeden sch*** bis zum letzten Pixel beschreiben obwohl im länger dauernden Projekt (und das auch jeden klar ist) 95% dieser Dokumentation hinfällig wird.

[Hansa]

Dejan Vu hat Recht. Der beste Kommentar ist selbsterklärender Quelltext. Dann sind nämlich die Kommentare direkt "impementiert". 8-) Bei folgender Zeile einen solchen Kommentar zu schreiben ist völliger Schwachsinn :

Delphi-Quellcode:

procedure test; // das ist die Prozedur Test

Hier allerdings (Pseudocode) :

Delphi-Quellcode:

Mwst := Mwst * 1.19;    // Achtung : MWST. zu Testzwecken in EXE eincompiliert !! Muss noch geändert werden! 10.XXX

Das wäre schon wichtig. Wobei das 10.XXX für Version steht. Dient halt zum Suchen im Source. Kann natürlich nach Belieben verfeinert werden. Und es gibt für solche Fälle direkt in Delphi ja auch noch ToDo.

[Nersgatt]

Zitat:

Zitat von Hansa (Beitrag 1267572)

Delphi-Quellcode:

Mwst := Mwst * 1.19;    // Achtung : MWST. zu Testzwecken in EXE eincompiliert !! Muss noch geändert werden! 10.XXX

Da würde sich IMO eine Warnung eher anbieten:

Delphi-Quellcode:

{$message Warn 'Achtung : MWST. zu Testzwecken in EXE eincompiliert !! Muss noch geändert werden!'}

Dann fällt es einem wenigsten bei jedem Erzeugen auf die Füße. Sofern das Fenster nicht sowieso mit Warnungen überquillt... :stupid:

Im übrigens bin ich ganz der Meinung von dejan vu.

[sx2008]

Zitat:

Zitat von Sherlock (Beitrag 1267561)

Wir ziehen Teile der Doku aus dem Quellcode.

Da kommt es drauf an, für wen die Software geschrieben wird.
Wer ist die Zielgruppe?
Handelt es sich um eine normale Applikation, Webservice, Dienst der verkauft wird um bei Kunden installiert zu werden?
Dann braucht man diese Art von Doku nicht.
Ist es eine Assembly,Unit,Klassenbibliothek die von anderen Programmierern eingebunden werden soll?
Dann gehört es dazu fast jeder public/protected Methode einen Kommentar zu verpassen und die API-Hilfe mit einem Tool erzeugen zu lassen.

[Hansa]

Ja, auch das ist richtig, aber mich stören trotzdem völlig unnötige Kommentare a la

Delphi-Quellcode:

i:= i + 1; // erhöht den Zähler um 1

Wer das nicht versteht (also ohne Kommentar, der ist ohnehin fehl am Platze :shock:)

[bernau]

Zitat:

Zitat von Hansa (Beitrag 1267579)

Ja, auch das ist richtig, aber mich stören trotzdem völlig unnötige Kommentare a la

Delphi-Quellcode:

i:= i + 1; // erhöht den Zähler um 1

Wer das nicht versteht (also ohne Kommentar, der ist ohnehin fehl am Platze :shock:)

Ich glaube wir sind uns alle einig, daß solche Kommentare unsinnig sind.

Aber es gibt Kommentare, die ausfürlicher sind als der "sprechende Procedurename". Und die sollte man verwenden.

Mein Code ist auch meist selbsterklärend. Aber manchmal gibt es "unsinnige Wünsche" von Kunden. So etwas kommentiere ich immer. Teilweise sogar mit Verweis auf die E-Mail des Kunden. Hat mir in der letzten Zeit schon manches Grübeln erspart.

[Dejan Vu]

Zitat:

Zitat von bernau (Beitrag 1267582)

Aber manchmal gibt es "unsinnige Wünsche" von Kunden. So etwas kommentiere ich immer. Teilweise sogar mit Verweis auf die E-Mail des Kunden.

Wir machen das über CVS.

[Chemiker]

Hallo,

also ich finde einen Kommentar nicht nutzlos.

Ich benutze Teilweise sehr alten ASM- und C/C++ -Code den ich selber mal vor 10-15 Jahren oder noch älter geschrieben habe und dank des Kommentars bin ich schnell in der Lage zu sehen wie ich die Routinen einsetzen kann und wie sie getestet worden sind.

Und sprechende Namen für Proceduren / Function sprechen heute, aber wie sprechen sie in 10 Jahren? Man ist nicht mehr im Thema und dann erscheint der Ablauf innerhalb der Procduren auch nicht mehr so klar das ist jedenfalls meine Erfahrung.

Bis bald Chemiker

[hoika]

Hallo,

auch ich bin der Meinung, dass JEDE Methode kommentiert sein muss.
Spätestens, wenn sich jemand in etwas einarbeiten soll, ist das wichtig.
Allerdings ist der Kommentar der Methode ein Sache,
weit wichtiger sind aber die Parameter- und Returnwertbeschreibung.
Ich halte mich übrigens an die Syntax von DelphiCode2Doc.

Bsp:

Delphi-Quellcode:

{*
  vergleicht 2 Strings, ohne Groß- und Kleinschreibung zu beachten

  @param  S1  erster String
  @param  S2  zweiter String
  @return  <1 S1<S2, >1 S1>S2, =0 S1=S2
}
function CompareText(const S1, S2: String): Integer;

Ich bin selber mal in die Falle getappt, dass ich auf -1 geprüft habe, statt auf <1

Dass man aus diesen Kommentaren auch schön eine Dokumentation rausziehen kann,
also die Code-Beschreibung nicht doppelt schreiben muss, ist ein angenehmer Zusatznutzen.


Heiko

Heiko

[mkinzler]

Zitat:

Zitat von Dejan Vu (Beitrag 1267583)

Zitat:

Zitat von bernau (Beitrag 1267582)

Aber manchmal gibt es "unsinnige Wünsche" von Kunden. So etwas kommentiere ich immer. Teilweise sogar mit Verweis auf die E-Mail des Kunden.

Wir machen das über CVS.

Was dann auch eine Form von Dokumentation/Kommentierung wäre.

Zitat:

Und sprechende Namen für Proceduren / Function sprechen heute, aber wie sprechen sie in 10 Jahren? Man ist nicht mehr im Thema und dann erscheint der Ablauf innerhalb der Procduren auch nicht mehr so klar das ist jedenfalls meine Erfahrung.

Aber wenn der Kommentar eine bloße Wiederholung des Funktionnamens ist, würde diese Dier dann genausowenig helfen.

[Dejan Vu]

Zitat:

Zitat von mkinzler (Beitrag 1267595)

Was dann auch eine Form von Dokumentation/Kommentierung wäre.

Die Frage ist ja nicht, ob man grundsätzlich dokumentieren sollte (überflüssige Frage), sondern ob man *im* Quellcode dokumentieren sollte. Jedenfalls hab ich das so interpretiert.

Wir haben z.B. unsere API mit 1-2 Sätzen im Code dokumentiert und sehr ausführlich im internen Wiki. Die Code-Dokumentation dient (in VS) dazu, beim Code-Proposal gleich was sehen zu können, auch wenn die Kommentare z.T. echt überflüssig sind, denn sowohl Methoden- als auch Parameternamen sind selbsterklärend. Man erkennt zwar, das eine Exception geworfen wird (kein Rückgabewert), aber trotzdem ist es besser, man sieht es in der Code-Dokumentation der Methode.

Das hat imho nichts damit zu tun, den Code durch Kommentare verständlicher machen zu wollen, denn das geht eigentlich immer schief und ist der falsche Weg.

Zitat:

Und sprechende Namen für Proceduren / Function sprechen heute, aber wie sprechen sie in 10 Jahren?

Na, Englisch bleibt Englisch.

Zitat:

...und dann erscheint der Ablauf innerhalb der Prozeduren auch nicht mehr so klar das ist jedenfalls meine Erfahrung.

Dann sind deine Methoden vielleicht noch zu lang.

Eine Methode besteht bei mir neben Zuweisungen und Methodenaufrufen aus entweder einer Schleife oder einem if-Statement, wobei ich selbst hier noch awäge, ob die Kontrollstruktur nicht doch in eine eigene Methode kommt. In jedem Fall löst die Methode genau eine Aufgabe, die sich im Namen wiederspiegelt. Verschachtelungstiefe maximal 2-4, wobei das Abstraktionsniveau gleich bleibt. Das verstehe ich auch noch nach 10 Jahren (und ich mach das seit 30), denn der Code ist -bis auf die unterste Ebene, ausschließlich englisch. Grammatikalisch nicht immer 100% korrekt, aber verständlich.

Ich muss ja nicht den gesamten Code, also bis zur untersten Stufe sehen. Es reicht doch, wenn ich verstehe, was die Methode macht:

Delphi-Quellcode:

Function ConvertBytesToHexString (const bytes : TByteArray) : String;
Begin
  Result := '';
  foreach byte in bytes do 
    Result := Result + Convert.ToHex(byte);
End;

Das versteht jeder auch nach 50 Jahren noch. Wie genau ein Byte in ein 'Hex' konvertiert wird, ist ja schnurz. Ich weiß, was ein Byte ist, ich weiß, was ein 'Hex' ist. Ich weiß, was 'Convert' bedeutet.

Beim Coden stelle ich mir immer die Frage:"Was für ein Gesicht macht mein Kollege, wenn er meinen Code liest?" und "Würde ich anfangen, zu stottern oder zu rudern, wenn ich ihm meinen Code erklären müsste?". Denn das muss ich, wenn er Schrott ist. Da ich meine Ruhe haben will, mach es lieber gleich so, das alles vorbildlich ist. Mäckeln tun die dann immer noch (liegt wohl in der Natur des Programmierers)x, aber dann auf sehr hohem Niveau: "Sollte die Methode nicht 'ConvertByteArrayToHexString' heißen? oder (hier) "Die Methode ist an der falschen Stelle: Verschiebe sie als statische Methode in unseren Converter". So macht programmieren Spaß, denn man pusht sich gegenseitig immer höher.

[mkinzler]

Zitat:

Die Frage ist ja nicht, ob man grundsätzlich dokumentieren sollte (überflüssige Frage), sondern ob man *im* Quellcode dokumentieren sollte. Jedenfalls hab ich das so interpretiert.

Manchmal hat man nur den Quellcode als Dokumentation (nicht wirklich zu empfehlen), bzw. die Kommentare werden automatisiert in eine Dokumentation überführt. Zudem ist es imho schon sinnvoll mögliche Problemfelden bzw. Besonderheiten direkt im Code zu dokumentieren.

[ChristianG]

Zitat:

Zitat von Dejan Vu (Beitrag 1267556)

Zitat:

Zitat von Sherlock (Beitrag 1267553)

Das mit dem Meth muss ich mal bei Gelegenheit ausprobieren (lassen).

Drogen und Programmieren passt irgendwie nicht. Entweder es wird viel zu kreativ und bunt, komplett verworren oder absolut krank. Hmm.

Zitat:

ISO 13485 entwickeln, da gibt es kein SW-Release ohne Doku.

Das betrifft doch nur die Doku und keine Quellcode-Kommentare, oder irre ich mich?

Da muss ich dir Widersprechen. Zum Beispiel die Entwickler von Goat Simulator mussten auf starken Drogen gewesen sein, um so ein komisches Spiel programmieren zu können.//Bevor Leute es falsch verstehen, das war ein Witz und Drogen sind allgemein nichts Gutes.
Bei solchen Ideen ist es aber wirklich nicht auszuschließen

Zu der Frage ob kommentieren Sinnvoll ist: Ja, wenn es sich um schwer zu verstehenden Sachen handelt, wie zum Beispiel ein Algorithmus. Bei simplen Aufgaben wie 2*2 ist es nicht empfehlenswert, da der Code unübersichtlich wird

[bernau]

Zitat:

Zitat von Dejan Vu (Beitrag 1267583)

Zitat:

Zitat von bernau (Beitrag 1267582)

Aber manchmal gibt es "unsinnige Wünsche" von Kunden. So etwas kommentiere ich immer. Teilweise sogar mit Verweis auf die E-Mail des Kunden.

Wir machen das über CVS.

Das interessiert mich. Wie sieht das in der Praxis aus? Der Hinweis auf den Kundenwunsch steht bei mir im Code und fällt sofort in's Auge. Wie sieht das im CSV aus? Wo steht der Hinweis? Muss ich selber aktiv einen Button drücken um diese Zusatzinfo zu sehen?

Delphi-Quellcode:

Procedure ZeigMalWas;
begin
  // 10.10.2012 - E-Mail von Meyer - Will ein Blinken im Sekundentakt.
  // LassBlinken(1);
  // 20.11.2012 - E-Mail von Müller - Blinken zu hektisch. Auf Wunsch nur alle 2 Sekunden.
  // LassBlinken(2);
  // 20.03.2013 - Telefonat mit Meyer - Vertrieb hat sich durchgesetzt. Blinken 2 mal pro Sekunde.
  LassBlinken(0.5);
end;

Hier sehe ich sofort, daß der Code geändert wurde. Und vorallem wieso etwas im Code geändert wurde. Fällt sofort in's Auge. Wie würde das im CVS aussehen?

[Stevie]

Zitat:

Zitat von bernau (Beitrag 1267611)

Delphi-Quellcode:

Procedure ZeigMalWas;
begin
  // 10.10.2012 - E-Mail von Meyer - Will ein Blinken im Sekundentakt.
  // LassBlinken(1);
  // 20.11.2012 - E-Mail von Müller - Blinken zu hektisch. Auf Wunsch nur alle 2 Sekunden.
  // LassBlinken(2);
  // 20.03.2013 - Telefonat mit Meyer - Vertrieb hat sich durchgesetzt. Blinken 2 mal pro Sekunde.
  LassBlinken(0.5);
end;

Hier sehe ich sofort, daß der Code geändert wurde. Und vorallem wieso etwas im Code geändert wurde. Fällt sofort in's Auge. Wie würde das im CVS aussehen?

In einer Versionsverwaltung wäre das in der Historie. Wenn man den Code liest, interessiert doch nicht mehr, wie oft das mal vor Jahren geblinkt hat und warum. Wenn du überall dieses Vorgehen hast, möcht ich nicht deinen Code lesen, denn der würde wahrscheinlich zu 99% aus altem auskommentierten Code bestehen.

[bernau]

Zitat:

Zitat von Stevie (Beitrag 1267613)

In einer Versionsverwaltung wäre das in der Historie. Wenn man den Code liest, interessiert doch nicht mehr, wie oft das mal vor Jahren geblinkt hat und warum. Wenn du überall dieses Vorgehen hast, möcht ich nicht deinen Code lesen, denn der würde wahrscheinlich zu 99% aus altem auskommentierten Code bestehen.

Der Code ist hier natürlich nur ein Beispiel und natürlich steht nicht in jeder Procedure solch ein Kommentar. Meine Frage war ja, wie es im CSV aussieht? Fällt so etwas sofort in's Auge, oder muss ich eine Aktion durchführen um diese Info's zu lesen. Mir hat es schon oft geholfen, daß ich "zufällig" diese Kommentare gelesen habe.

[JasonDX]

Zitat:

Zitat von bernau (Beitrag 1267615)

Der Code ist hier natürlich nur ein Beispiel und natürlich steht nicht in jeder Procedure solch ein Kommentar. Meine Frage war ja, wie es im CSV aussieht? Fällt so etwas sofort in's Auge, oder muss ich eine Aktion durchführen um diese Info's zu lesen. Mir hat es schon oft geholfen, daß ich "zufällig" diese Kommentare gelesen habe.

Dazu muss eine Aktion durchgeführt werden. Hat auch seinen Grund, da zu 99% der Zeit diese Information nicht sinnvoll/hilfreich und damit platzraubend ergo kontraproduktiv wäre.
Diese Information als Kommentare in den Code zu setzen ist nur in wenigen Ausnahmen sinnvoll, und entsprechend spärlich sollten diese Kommentare verwendet werden.