Myślę, że w tym względzie musimy oddzielić „zwykły” kod od publicznych interfejsów API . Jeśli chodzi o zwykły kod, zdecydowanie zgodziłem się z większością innych osób odpowiadających w tym kodzie, że kod ten powinien być samodokumentujący i czytać prawie jak proza . Jeśli mój kod nie jest taki, to zwykle jest to moja wina, więc zamiast dokumentować, należy go ponownie opracować. Małe metody, które robią tylko jedną rzecz na raz, pracując na jednym poziomie abstrakcji, o poprawnej i opisowej nazwie , mogą pójść w świetny sposób do osiągnięcia tego.
Problem z komentarzami polega na tym, że gniją. Jak tylko dodasz komentarz, zacznie on żyć niezależnie od kodu, który mu towarzyszy. Jak duża jest szansa, że następny programista, który zmodyfikuje kod, również odpowiednio zaktualizuje powiązane komentarze? Z mojego doświadczenia wynika, że blisko zera. Efektem końcowym po kilku modyfikacjach jest to, że komentarz intryguje lub wprowadza w błąd ludzi zamiast im pomagać.
Możliwe wyjątki to kod zoptymalizowany pod kątem wydajności lub użycie określonego algorytmu . W takim przypadku przydatne jest dodanie komentarzy opisujących, jak wygląda kod, odniesienie do algorytmu itp.
Najważniejsze prace na ten temat to Clean Code .
OTOH publiczny interfejs API również powinien być dobrze udokumentowany w Javadoc . Ponieważ może być używany przez niezliczoną liczbę nieznajomych z niezwykle różnorodnymi umiejętnościami i założeniami, należy podjąć wszelkie środki ostrożności, aby korzystanie z niego było tak proste i jednoznaczne, jak to możliwe. Jest to nadal w dużej mierze kwestia właściwego zaprojektowania interfejsu API, ale dokumentacja również odgrywa ważną rolę.