Quellcode Kommentieren

[Dejan Vu]

Zitat von mkinzler:

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.