On Sat, 2004-12-11 at 17:13 +0100, Erik Schanze wrote:
Ich suche nach Informationen oder Erfahrungen von Entwicklern, wie man am besten Sourcecode (speziell C++) kommentieren sollte, damit die Kommentare einheitlich und gut verarbeitbar sind. Gibt es (Quasi-)Standards?
Wenn man sich so umsieht, scheint sich doxygen zum Quasistandard gemausert zu haben. Und das nicht umsonst, denn es ist wirklich sehr flexibel. Wir benutzen es z.B. zum generieren von HTML für das Entwicklerteam und zum genererien von PDF (über Latex) für die Akten (TÜV z.B.). Doxygen hat außerdem den Vorteil, daß es alle wesentlichen Markup-Typen unterstützt. Das ist nützlich, wenn man bereits kommentierten Code hat. Speziell unterstützt es doc++, Javadoc und kdoc. C#-Kommentare (XML) sollen wohl bald folgen. Wenn man sich einen dieser Stile herauspickt, kann man später auch zu dem entsprechenden Tool wechseln.
Was den Kommentierstil angeht, habe ich immer folgende Empfehlung parat: Normale Quellcodekommentare immer mit "//" einleiten, damit man beim Debugging größere Quellcodeteile mittels "/* */" auskommentieren kann. Ausnahme: die doxygen-Kommentare, da die meistens etwas länger sind und sowieso außerhalb der Methoden stehen. Kommentiere innerhalb der Methoden, WARUM Du etwas tust, nicht WAS Du tust. Wer sich in die Tiefen der Quellen vorwagt, wird das WAS sehen. Das WARUM aber erfordert Wissen um den Kontext, welches beim Betrachter in dem Ausmaß evtl. nicht vorhanden ist. Beispiel:
++i; // inkrementiere den Zähler [Ach nee...]
myWidget->SetCaption(dbConnection->getCurrentValue(3)); // stelle den Kundennamen im Textfeld dar
Im ersten Fall erzeugst Du nur Rauschen, im zweiten Fall ist das Wissen um die Datenbankstruktur erforderlich. Durch den Kommentar erkennt der Nutzer was da passiert, ohne daß er kompliziert ausknobeln muß, was denn Wert 3 in der Datenbank ist.
Genug doziert, HTH, Eric