Quellcode Dokumentieren
bearbeitet von AugeHallo
> Wie Dokumentiert und kommentiert man einen bestehenden fertigen Quellcode???
Kommentare sollen nicht das Offensichtliche kommentieren, sondern das, was man aus dem kommentierten Quelltext nicht direkt entnehmen kann. Wenn man, um ein **stark** vereinfachtes Beispiel zu konstruieren, `echo htmlspecialchars($myText);` kommentiert, braucht niemand, der den Quelltext auch nur annähernd verstehend lesen kann, die Info dass da ein Text dem Kontext HTML entsprechend behandelt wird, sondern, wenn die Anweisung denn überhaupt kommentiert werden müsste, allenfalls, was denn in `$myText` steckt.
> wann ist es günstiger ***//*** zu verwendenn un wann /*****...******/* in mehreren zeilen? lohnt es sich mitten in die funktionen zu kommentieren oder in die schleifen, bedingungen oder ist es eher sinnvoll das außerhalb zu machen?
Es gibt fertige Schemata für Code-Formatierung, zu denen auch die Art der zu benutzenden Kommentare [^1] gehört. Wenn du in dieser Hinsicht deinen eingenen Vorlieben frönst, ist das aber auch i.O., solange du nicht in einem Team programmierst. Dann sollte es eine verbindliche Vereinbarung zur Code-Formatierung und damit auch zur Formatierung der Kommentare geben.
Die Entscheidung über die Kommentarformatierung hängt also von verschiedenen Dingen ab. Zuallererst von der benutzten Sprache.
Tschö, Auge
[^1]: Vorausgesetzt, es gibt in der betreffenden Sprache mehrere Möglichkeiten Kommentare zu formatieren.
--
Es schimmerte ein Licht am Ende des Tunnels und es stammte von einem Flammenwerfer.
Terry Pratchett, „Gevatter Tod“