Kommentieren

Kommentare sind vor allem bei langen Codes sehr wichtig. Sie dienen der leichteren Verständlichkeit und können an jeder Stelle des Programms stehen. Wenn man längere Zeit nicht an einem Code arbeitet, helfen Kommentare ihn schnell wieder zu verstehen. Leute, die nicht selbst daran gearbeitet haben, können sich so ebenfalls leichter im Code zurechtfinden.

Kommentare haben keinen direkten Einfluss auf das Programm und werden vom Compiler ignoriert.

Kommentare sollten jedoch so dosiert werden, dass sie nicht ablenken. Häufig ist es viel wichtiger zu dokumentieren, warum etwas gemacht wird, als was genau macht wird.

Falsch

Unnötige und teilweise zum Code wiedersprüchliche Kommentare. Dazu haben wir auch eine Auflistung mit Extrembeispielen.

int multipliziere(int a, int b)
{
   // Hier werden die Variabeln temporär gespeichert <-- Veraltet
   // hier wird gerechnet                            <-- Vollkommen unötig
   // a ist die eine Variable und b die andere       <-- Vollkommen unötig
   // a und b werden miteinander multipliziert       <-- das steht genauso im Quelltext, auch die Funktion lässt das vermuten
 
   return a * b;
}

Besser

Hier ist kein Kommentar überflüssig, und der vorhandene beschreibt was die Funktion tut.

// Der Zeiger auf diese Funktion wird als Parameter der Funktion XYZ verwendet, die
// zwei Variablen miteinander verrechnen soll. Alternativ kann auch addiere übergeben
// werden.
 
int multipliziere(int a, int b)
{
   return a * b;
}

Am Besten - Doxygen

Am Besten ist es wenn man seine Funktionen mit einer von Doxygen verwertbaren Form versieht. Dadurch kann man später automatisch eine Dokumentation zu dem Code generieren lassen. Und wenn man sich das gleich von Anfang an angewöhnt ist es auch nicht viel extra Aufwand.

Die erste Zeile gibt kurz bekannt, was die Funktion macht, es folgt eine genauere Erklärung und anschließend werden Parameter und Rückgabewert dokumentiert.

//------------------------------------------------------------------------------
///
/// Berechnet das Produkt von zwei Variablen
///
/// Der Zeiger auf diese Funktion wird als Parameter der Funktion XYZ verwendet, die
/// zwei Variablen miteinander verrechnen soll. Alternativ kann auch addiere übergeben
/// werden.
///
/// @param a  Erster Faktor
/// @param b  Zweiter Faktor
///
/// @return Produkt der beiden Faktoren
 
int multipliziere(int a, int b)
{
   return a * b;
}