Quellcode Kommentieren

[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.