Witam.
Od zawsze opisywałem mój kod napisany w PHP po swojemu, tj. komentarze do wszystkich funkcji był takie, abym ja wiedział co, gdzie, jak i po co. No, ale pojawił się taki problem, że nie opisuję kodu zawsze tak samo, w wyniku czego nieraz nie potrafię zrozumieć opisu funkcji napisanej parę miesięcy wcześniej i muszę dogłębnie się wczytywać w kod, aby znów wiedzieć o co chodzi. No i tu pojawia się moje pytanie, które pewnie zostało podane już parę razy na forum(sory, ale ja zawsze staram się pomóc nawet jak było! wiadomo, nieraz nie chce się szukać, to ktoś pomoże), a mianowicie jakie są najlepsze, najpopularniejsze techniki opisywania kodu. Jak go opisać tak by był w miarę czytelny dla innego programisty, który po samym opisie funkcji będzie wstanie wiedzieć co w niej zachodzi i z czego, bez jej analizowania. Przydałoby się, aby to był również taki standard opisywania, który posiadałby jakieś narzędzie do tworzenia na podstawie opisów dokumentację(w miarę automatycznie), tak, ażeby zwykły zjadacz chleba też mógł wiedzieć jak wykorzystać coś co mu udostępnię i nie musiał się zagłębiać w obiekty etc.

Bardzo proszę o sensowne porady
Pozdrawiam

Narzędzie: phpDoc

Odnośnie samego stylu opisywania funkcjonalności realizowanej przez kod to nie spotkałem się z jakimiś zasadami, jednak podstawowym wyznacznikiem dobrego opisu powinno być opisanie w krótkich zdaniach podstawowej funkcjonalności.

edit: Swego czasu korzystałem jeszcze z narzędzia naszej rodzimej produkcji: http://www.invenzzia.org/en/projects/typefriendly

Popieram @askone co do PHPDoc'a - dodam przy tym, że na chwilę obecną opisywanie w ten sposób jest chyba najlepszym rozwiązaniem gdyż:

1. Dobrze znane środowiska IDE do PHP (eclipse, netbeans itp..) nie najgorzej (z małymi wyjątkami) składnie PHP interpretują co pozwala na tzw "dymki" i "pdopowiedzi" podczas pisania aplikacji - więc nie tylko chodzi o to by ktoś wiedział o co chodzi
2. Te same IDE dodatkowo mają wbudowaną obsługę generacji PHPDoc'ów, która co prawda nie zawsze jest rewelacyjna ale pozwala skrócić czas opisywania i komentowania kodu

Co do samego komentowania polecam stosować komentarze dodatkowe (objaśniające dany algorytm lub działanie) tylko w wyjątkowych styuacjach...

To znaczy:

[PHP] pobierz, plaintext 
$a = mysql_query("SELECT * FROM tabelka");
while($b = mysql_fetch_assoc($a)) // Pobranie wszystkich rekordów
{
   // ....
}
[PHP] pobierz, plaintext 

Tego typu komentarz jest zbędny bo widać to gołym okiem... ale już:

[PHP] pobierz, plaintext 
 
// jakiś kod...
 
$arr = prepareData($result); // Zmienia kodowanie wszystkich wierszy na UTF-8
 
// jakiś kod...
 
[PHP] pobierz, plaintext 

taki przypadek ma sens bo użytkownik nie musi zagłebiać się wstepnie co robi funkcja "prepareData" - bo w skrócie jest to opisane

Reasumując:

1.PHPDoc - pobaw się jakimś IDE i zobacz jakie to proste
2.Komentarze objaśniające tylko tam gdzie ma to sens

Serdeczne dzięki! Zainteresuje się PHPDoc i zobaczymy co z tego wyjdzie

Pozdrawiam

1. Wspomniane już komentarze PHPDoc - przy czym do samego generowania dokumentacji na ich podstawie nie poleciłbym phpDocumentora, często utożsamianego z samymi komentarzami.
2. Przede wszystkim samodokumentujący się kod. Czyli w miarę możliwości nie $data = prepareData($data); // Zmienia kodowanie na UTF-8, a $data = convertToUTF8($data);.

ad 2. W pełni się zgadzam - moja zagrywka z tą "dziwną" nazwą miała podkreślić jedynie konieczność wstawienia komentarza