Kommentierungsrichtlinien



  • Hallo,

    bisher habe ich meine Programme nach eigenem Gutduenken kommentiert. Da eines allerdings inzwischen recht lang ist (> 10000 Zeilen) und ich ausserdem demnaechst Programmieranfaenger anleiten muss, vermute ich, ein reflektierteres Vorgehen koennte hier lohnenswert sein.

    Von daher: Kennt jemand gute Kommentierungsrichtlinien (sei es online oder in einem Buch)? Bisher habe ich nur alte Richtlinien fuer C aus den 80ern gefunden bzw. die 1,5 Seiten, die dazu im Stroustrup stehen.



  • Ältere Kommentierungsrichtlinien besagen, dass Quellcode zu ca. 30% aus Kommentaren bestehen solle. Vermutlich steht sowas vor allem in deinen C-Richtlinien von anno dunnemals.

    Diese Richtlinien sind nicht mehr aktuell, heute ist die allgemeine Ansicht eher, dass Code sich möglichst selbst kommentieren solle. Das bedeutet vor allem, sprechende Variablennamen zu benutzen.

    Kommentare sind nur dann angebracht wenn sie Informationen bringen, die man nicht in den Code einbringen kann, z.B. Begründungen für Designdetails und Erklärungen, um welchen Algorithmus es sich bei den folgenden N Zeilen handelt.
    Weitere kurze Kommentare die vorkommen sind Gliederungskommentare, z.B: um eine Datei in Abschnitte zu unterteilen (nur wenns nicht anders machbar ist und die Datei wirklich so lang sein muss).

    Speziell in C++ sind Kommentare zu den compilergenerierten Funktionen (Default-Ctor, Copy-Ctor, op= und Dtor) oft sinnvoll, um einfach anzuzeigen dass es beabsichtigt ist, sie generieren zu lassen und sie nicht einfach zu vergessen.

    Das Problem bei Kommentaren ist einfach folgendes: sie sind nicht automatisch aktuell. Wenn mal eben eine kleine Änderung am kommentierten Code erfolgt, wird gerne vergessen, den Kommentar auch entsprechend zu ändern. Der Kommentar ist dann nicht mehr aktuell und liefert falsche Informationen - und das ist schlimmer als garkeine Informationen.



  • Es kommt darauf an, was man mit den Kommentaren alles ermöglichen will.

    Ich verwende Beispielsweise doxygen, womit man eine Codedokumentation mit Hilfe der Kommentare extrahieren kann. Wenn man das Tool nutzt, so muss man sich natürlich auch an die Vorgaben von doxygen halten.

    Nachtrag: Ansonsten trage ich die Meinung von pumuckl wegen selbstdokumentierenden Code, und sehe Kommentare im Quellcode in der Regel als Indiz für zu lange Funktionsrümpfe, oder schlecht gewählte Bezeichner an. Ich habe mir dennoch die doxygen-Kommentare im Header angewöhnt (Wegen der optionalen Dokumentationserzeugung).

    Persönlich dokumentiere ich eigentlich 95% nur im Header (Weil ich es so sehe: Das ist die erste Stelle die man sich anschaut, wenn man programmiert - Da man vermeiden sollte gegen die konkrete Implementierung zu entwickeln).

    Dies hat zudem den Vorteil das man auch als Lehrer/Dozent... Vorgaben in Form eines Headers machen kann (ohne eine Implementierung vorzugeben). Beispielsweise kann der Dozent dann schon ein Programm schreiben, um die Implementierung der Schüler zu testen (Da die Schnittstellen, die Vor- und Nachbedingungen... bekannt sind). Im Gegenzug schränkt es natürlich auch den Gestaltungsspielraum ein, und ich würde auch nur den public-Bereich einer Klasse vorgeben (Was an Membervariablen, was an Hilfsfunktionen... verwendet wird, obliegt dem Schüler - dies sind bereits Implementationsdetails).

    cu André



  • Hi

    Ich kommentiere alles nach Javadoc (egal in welcher Sprache ich gerade Programmiere)
    http://java.sun.com/j2se/javadoc/

    Finde das System super, weil es einfach und trotzdem sehr mächtig ist.

    Zu Kommentar Regeln kann ich dir leider nichts sagen. Aber das von pumuckl hört sich doch recht vernünftig an 🙂

    Keros



  • Ich gebe meinen Vorrednern auch Recht möchte aber noch eine klare Aussage eines Profs von mir anhängen:

    "Kommentiere nie was du tust, sondern warum du etwas so tust!"

    Das "was" erklärt der Code ja selbst 😉

    Professor


Anmelden zum Antworten