Automatisch Laufen einer Person

[Kyuu]

Kommentare sollten - ausgehend von einer sauberen Programmierung - nicht beschreiben was der Code macht, sondern wieso er da ist. Was der Code macht sollte aus dem Namen der Routine hervorgehen. Der folgende Kommentar ist zum Beispiel vollkommen redundant:

Code (C++):

 
/* Tut dies und das. */
void tueDiesUndDas() {
    /* ... */
}
 

Während dieser durchaus gerechtfertigt ist:

Code (C++):

 
void tueDiesUndDas() {
    /* ... */
    A* a = new A();
    /* da ältere MSVC-Versionen bei fehlgeschlagener Speicherreservierung
        statt std::bad_alloc zu werfen einen Nullzeiger zurückgeben */
    if (!a) {
        throw std::bad_alloc();
    }
    /* ... */
}
 

Oft wird natürlich auch die Kommentierung des Rückgabewertes, sowie der Parameter einer Routine benötigt, besonders bei komplexeren Datenstrukturen in Verbindung mit fehlender automatischer Speicherbereinigung (C/C++), oder der Vermerk der Vor- und Nachbedingungen, sowie der Invarianten (Design By Contract). In diesen Fällen sind auch seitenlange Kommentare völlig gerechtfertigt.

Die Aussage, dass es unsinnig ist eine Zeile Code mit 4 Zeilen Kommentar zu versehen ist selbst unsinnig. Vom Code- zu Kommentarzeilen-Verhältnis kann man nicht auf den Sinn, oder Unsinn eines Kommentars schließen.

Das Kommentar-Beispiel von makenshi dient eher der API-Dokumentation für Tools wie Javadoc, oder bei C/C++ Doxygen, was natürlich auch seinen Sinn hat, aber als Beispiel dafür, wie professioneller Code kommentiert wird, würde ich es nicht nehmen. Ein allgemeingültiges Beispiel kann man sowieso schlecht finden, da es immer auf die Situation ankommt.