Quellcode Dokumentieren

[.MB]

Liebe Community,

Wie Dokumentiert und kommentiert man einen bestehenden fertigen Quellcode???

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?

guten Rutsch wünsche ich euch,

mb

[Auge]

Hallo

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

PS: Das Meta-Forum ist nicht das Fachforum. => Meldung (wird wohl verschoben).

---

1. Vorausgesetzt, es gibt in der betreffenden Sprache mehrere Möglichkeiten Kommentare zu formatieren. ↩︎

[Der Martin]

Hallo,

Wie Dokumentiert und kommentiert man einen bestehenden fertigen Quellcode???

so, dass der Kommentar auf möglichst klare Weise erläutert, was der Sinn des Codes ist. ;-)
Also ich weiß nicht, wie "man" das am besten macht, ich kann dir nur sagen, wie ich es normalerweise mache.

wann ist es günstiger // zu verwendenn un wann /.../ in mehreren zeilen?

Das hängt zunächst mal von der Sprache ab. CSS kennt beispielsweise keine einzeiligen Kommentare mit //, Javascript oder C jedoch schon. Ich habe mir angewöhnt, in Sprachen, die einzeilige Kommentare mit // oder ähnlichem unterstützen (in Assembler oft das Semikolon), ausschließlich diese zu verwenden, und mehrzeilige Kommentare mit Anfangs- und Endtoken nur, um testweise einen bestimmten Codeabschnitt unwirksam zu machen.

lohnt es sich mitten in die funktionen zu kommentieren oder in die schleifen, bedingungen

Ja. Mein Motto ist immer: Wenn man den eigentlichen Code ausblendet und nur die Kommentare bleiben, dann sollte der Programmablauf dennoch grob erkennbar und nachvollziehbar sein.

oder ist es eher sinnvoll das außerhalb zu machen?

Sowohl, als auch. Als "Überschrift" zu einer Funktion notiere ich oft einen Kommentar, der den Zweck, die Aufrufparameter und das Funktionsergebnis erklärt, ggf. die zulässigen Randbedingungen oder ein dokumentiertes Verhalten im Fehlerfall.

So long,
 Martin

[.MB]

Gut besten Dank,

ein fröhliches neujahr,

mb