Heute hatte ich eine Diskussion über die Art und Weise wie man in Java dokumentiert. Was sind gute Kommentare? Was muss dokumentiert werden? Was kann man weglassen?
Ich finde zu diesem Thema die Meinungen von Robert C. Martin gut, die er in seinem Buch Clean Code: A Handbook of Agile Software Craftmanship. Prentice Hall PTR. 2008 unter dem Kapitel 4 “Comments” vertritt.
Ein paar Auszüge:
Seite 63:
It is just plain silly to have a rule that says that every function must have a javadoc, or every variable must have a comment. Comments like this just clutter up the code, propagate lies, and lend to general confusion and disorganisation.
Seite 64f.:
And then there’s this paragon of redundancy:
/**
* Returns the day of the month.
*
* @return the day of the month.
*/
public int getDayOfMonth() {
return dayOfMonth;
}
Seite 71:
As useful as javadocs are for public API’s, they are anathema to code that is not intended for public consumption.
Auch wenn ich hier Auszüge aus dem Kapitel “Bad Comments” bringe, so halte ich Kommentare und Dokumentation zum Job eines Softwareentwicklers. Öffentliche Methoden müssen eine nützliche Dokumentation haben (Bitte aber nicht wie in getDayOfMonth 😉 ). Auch macht man sich oder seinen “Nachfolgern” oft das Leben wesentlich leichter seine Intention zu erklären, warum etwas genau so und nicht anders gemacht hat. Alles im Buch beschriebene möchte ich nicht hier wiedergeben. Einfach lesen.
Da aber Softwareentwicklung in den meisten Fällen im Team erfolgt, sollte man sich aber auf Regeln einigen und diese dann auch einhalten.
ollin's 