Jetzt mal eine Frage an euch, habe neulich mal jemanden geholfen und würde gern wissen ob dieser Kommentar edel, hilfreich und gut sei bzw. "richtig" sei - oder ob er das Wie aber nicht das Was beschreibt:
Vorab: das Thema ist ja recht subjektiv, daher alles persönliche Meinung
- Mit JavaDocs wird die API dokumentiert, nicht der Code.
- Wäre die Methode private, bräuchte man keine JavaDocs.
- Welche Informationen enthält der Kommentar?
- Helper-Methode: uninteressant.
- Die Methode verarbeitet den Baum rekursiv. Ein Implementierungsdetail, das sich - wenn man es denn überhaupt nennenswert findet - leicht im Namen unterbringen lässt (transformTreeRecursively).
- Angabe der Typparameter und Parameter: steht schon in der Deklaration
- Gibt den transformierten Baum zurück... Das ist, was man von einer Methode, die einen Baum transformiert, auch erwarten würde.
Als Util-Methode könnte man sie in eine Klasse Trees packen und transformRecursively benennen. JavaDocs - muss jeder selbst wissen - interessant wäre da eher der Hinweis, ob der übergebene Baum verändert wird.
Das grds. Problem bei Kommentaren ist, dass sie in der Regel einmal geschrieben werden, so gut wie nie aktuell gehalten werden. Es ist toter Text, der vom Compiler nicht verarbeitet wird. Beim Lesen des Codes wird der Kommentar meist überlesen, weil er kein Schw... interessiert.
Und jetzt: frohe Weihnachten.