"Wieso überhaupt kommentieren?" ist eine Frage, die ich mir auch oft gestellt habe. Kommentieren ist eine lästige Sache. Aber inzwischen musste ich erkennen, das es weniger Mühe macht gleich mitzukommentieren, als danach oder sich später so in den Quellcode wieder einzuarbeiten.
Gerade bei Objektorientierter Programmierung ist die Dokumentation ein wichtiger Teil der Entwicklung, denn nur so ist es anderen Programmieren möglich die Komponenten zu verwenden und weiterzuentwickeln. Wichtige Dinge sind hierbei Anzahl und Art der Parameter und der Rückgabewerten, die zu erwartenden Exceptions und die Wirkung der einzelnen Methoden.
Dies ist aber bei externen Dokumentationen eine mühselige Arbeit. Mit dem Tool Javadoc ist es möglich die Dokumentation direkt in den Quellcode zu schreiben und es generiert daraus dann eine externe Dokumentation im gewünschten Format.