Kommentierst du alle Programme, die du schreibst?
Ja…. und nein.
Wenn Du /* Kommentare */ meinst oder Beschreibungen für Doxygen (was über meinen Quelltext drübergeht und Dokumentation erstellt, aber nur für wenige Klassen tatsächlich Kommentare findet), dann eher nicht.
Ich achte aber darauf, dass Klassen einen systematischen Aufbau haben. Macht man eine Headerdatei auf, sind alle gleich angeordnet, es gibt etwa 10 Unterpunkte, nach denen ich sortiere: dynamische Member, Konstruktoren, statische Member, Getter/Setter, Operatoren, Methoden. Wenn ich also wissen will, wie ein Getter heißt, finde ich die etwa in der Hälfte der Klassedeklaration.
Ich benutze Vorsilben: Is, Get, Set und As für Getter und Setter. Für Methoden zur Konvertierung To. Ich vermeide Getter und Setter, wenn sie nicht virtuell sind. Das hält die Klassen überschaubar.
Funktionalität muss sich in logischen Namenbereichen wiederfinden. Ich versuche also auf statische globale Funktionen zu verzichten, um die Funktionen schnell finden zu können.
Logischerweise verwende ich für Typen sprechende Namen. Ich vermeide Primitive. Eine Funktionsdeklaration int func(int i, int j, int k, int l, int m) habe ich im Job schon gesehen… Jedes int hatte eine andere Bedeutung. Sowas gibt’s bei mir nicht: Bei mir hat alles Namen und die Typen sind nicht implizit überführbar. Daraus ergibt sich, dass der Name der Funktion und die Namen der Typen eigentlich bereits die grundlegende Dokumentation ergeben.
Darum dokumentiere ich nur wenig mit Doxygen. Wenn der Parameter von Polygon const & Solid::GetPolygon( PolygonIdx pi ) vom Typ PolygonIdx ist, schreibe ich als Dokumentation für den Parameter “Polygonindex” dahinter… was soll das? Wenn die Funktion in einem Solid GetPolygon heißt und ein Polygon zurückliefert und einen PolygonIndex erhält, dann ist das der geometrische Körper offensichtlich aus Polygonen ausgebaut, die man der Reihe nach abrufen kann. Was genau soll ich da dokumentieren… steht doch da!?
Wenn ich kommentiere, dann ist das eher eine Doxygen-Seite wo ich ein Konzept festhalte. Der Rest ergibt sich aus den Klassennamen. Ich erkläre keine Idiome, keine DesignPatterns, dafür gibt es Bücher. Ich erkläre ja auch nicht die Programmiersprache. Algorithmen sollten einen erkennbaren Aufbau haben: Vorbereitung, Handlung, Nachbereitung, Ergebnis. Das kann man durch Leerzeilen oder mal eine optische Linie /* ———————————— */ andeuten. Aber da braucht man keinen Roman.
Aktuell aus einem Quelltext, der nicht von mir stammt:
        // jetzt RENDERN ///////////////////////////////////////// 
        model.render( *this ); 
        // jetzt RENDERN ///////////////////////////////////////// 
Hilft der Kommentar, um zu verstehen, was da passiert? Und wenn nicht, warum steht er da? Warum lese ich ihn, nur um zu verstehen, dass er überflüssig ist, schließlich sagt der Code viel klarer aus, dass es ein Model gibt, was jetzt mit Hilfe dieser Klasse gerendert wird. Die Linie signalisiert genauso klar, dass hier die Vorbereitung zu Ende ist und danach die Nachbereitung kommt, es steht aber nichts drin, was ich lesen muss.
Kommentare im Code gibt es dann, wenn ich wirklich kranke Sachen mache. Zur Laufzeit des Programms Maschinencode generieren und ausführen ist etwas, wo man irgendwann viel mit void * zu tun hat und reinterpret_casts und da sollte man hier und da schonmal ein Wort zu schreiben.
Ansonsten sind Kommentare meistens irgendwann falsch, das heißt er beschreibt den Code nicht mehr. Eine kleine Änderung hier, eine kleine Änderung da und nie hat jemand den Kommentar angepasst.
Quelltext, der kommentiert werden muss, ist in der Regel ein Hinweis darauf, dass man ihn falsch geschrieben hat.
Umgekehrt entsteht eher Dokumentation. Muss ich über einen Algorithmus länger nachdenken, beschreibe ich ihn als Kommentar. Dann schreibe den Kommentar solange um, bis sich die Handlungsabfolge darin wiederfindet und implementiere dann den Algorithmus zwischen dem Kommentar. Der Kommentar bleibt dann stehen.
Also zurück zur Frage: Ich kommentiere sehr wenig, ich achte aber sehr darauf, möglichst wenig kommentieren zu müssen und baue auch Strategien auf, meinen Quelltext leicht verständlich und schnell durchsuchbar zu halten.