Kommentare haben fast so einen schlechten Ruf wie Testklassen, dabei sind sie fast genauso wichtig wie diese. Schliesslich helfen beide dabei, wartbare Applikationen zu schreiben. Je nachdem ist man selbst der direkt Betroffene, wenn man in ein paar Monaten an dieser Applikation eine Anpassung machen muss und nicht mehr weiss, um welchen Spezialfall es sich hier genau handelt. Deshalb lohnt es sich hier ein bisschen Zeit zu investieren. Ich möchte kurz meine Erfahrungen zum Thema 'Sourcecode kommentieren' beschreiben.

Nie den Sourcecode 1:1 kommentieren

Es bringt nichts im Kommentar zu schreiben, was bereits programmiert wurde. Wieso sollte jemand folgendes lesen wollen?

//füge Adresse in Adressliste ein
adresslist.add(adress);

Das hilft niemandem weiter. Kommentare müssen einen Mehrwert liefern. Also macht es zum Beispiel Sinn vor einem komplexen Algorithmus dessen Namen in den Kommentar zu schreiben.

Bei Business-Funktionen ist es sinnvoll Referenzen in die Spezifikation oder ins Issue Management System in die Kommentare zu schreiben. Wenn aus der Spez oder dem Issue dieses Implementierungsdetail nicht hervorgeht und es sich um einen genügend komplexen Codeblock handelt, sollte hier direkt ein Kommentar stehen, was man hier programmiert.

Sprache der Kommentare

Wenn das Team deutsch spricht, alle Dokumente deutsch sind und der Sourcecode intern bleibt, dann ist es irr englisch zu kommentieren.

JavaDoc in Schnittstellen

Schnittstellen beinhalten Methoden, die von anderen Teilen der Applikation aufgerufen werden. Hier ist eine Dokumentation besonders wichtig, da IDE's die Beschreibungen bei der Arbeit mit diesen Schnittstellen darstellen.

Keine Namen

Es bringt nichts in Kommentaren den eigenen Namen hineinzuschreiben. Diese Information kommt aus dem Sourcecode Verwaltungssystem (SVN, CVS, ...).

Review

Wie "normaler" Code sollten auch Kommentare reviewt werden. Was nützt ein Kommentar den niemand sonst versteht?