Komentarze - kiedy i jak stosować?

W książce "clean code" czytałem, że komentarze powinny być stosowane jak najrzadziej i tylko wtedy, kiedy jest to konieczne. W kodzie opensourcowego frameworka "kohana" widziałem dokumnetację przed każdą klasą/funkcją i praktycznie każdą linijką kodu. Pytanie - jak poprawnie komentować kod (jeśli piszę coś, co będzie miało API i będzie wykorzystywane przez userów-programistów) ?

Głównie:

• pisać przed każdą klasą/funkcją, do czego służy?
• wypisywać parametry funkcji / zwracane wartości w dokumentacji ? (@param integer ...)

itp.

Komentowanie publicznego API to trochę inna sprawa niż komentowanie kodu. Obecnie najpopularniejsze są systemy, w których API dokumentujemy bezpośrednio w kodzie za pomocą specjalnej składni, przed metodami na przykład. Natomiast same komentarze w kodzie mają na celu ułatwienie w zrozumieniu tego kodu. Mówiąc: komentarze powinny być stosowane jak najrzadziej, mamy na myśli: piszmy kod tak, by powodów do wstawiania komentarzy było jak najmniej.

Hmm, a jak sprawa wygląda z tworzeniem dokumentacji? Nie ma narzucania typów argumentów jak w C. Generowanie dokumentacji kodu w jakimś GUI też jest fajną sprawą. Ale z drugiej strony takie komentarze "zaciemniają" kod. Jak to powinno wyglądać?

PHP nie narzuca typów, ale funkcja może jakieś typu oczekiwać, ten typ mówisz w dokumentacji. Komentarze według mnie nie zaciemniają kodu, zresztą wiele IDE potrafi je "zwinąć". A za to dają ci podpowiadanie składni przy wywoływaniu metod czy odwoływaniu do pól.