Uwaga! Informacje na tej stronie mają ponad 6 lat. Nadal je udostępniam, ale prawdopodobnie nie odzwierciedlają one mojej aktualnej wiedzy ani przekonań.
Tue 26 Feb2008
W nowym, utworzonym przeze mnie dziale forum - Porady - dwie osoby zdecydowały się założyć temat poświęcony czytelności kodu i komentarzy - [1], [2]. Wyniknęły z tego ciekawe dyskusje na tematy, które dotyczą każdego programisty:
Gdzie i jakie komentarze pisać? Czy lepiej więcej, czy mniej komentarzy?
Czy unikać komentarzy /* */ aby można było obejmować w nie większy fragment kodu, czy większe fragmenty wyłączać dykrektywą #if 0?
Czy komentować pod kątem generatora dokumentacji takiego jak Doxygen?
Czy wcięcia robić za pomocą spacji, czy tabulacji?
Wg jakich zasad dzielić kod na funkcje i pliki?
Czy warunki wstępne i końcowe funkcji zapisywać jako asercje w kodzie, czy jako komentarze w nagłówku?
Czy stosować notację węgierską?
Jak pisać klamerki? Jak zapisywać identyfikatory? itd...
Właściwie to staram się tylko obserwować, jak wygląda podejście profesjonalistów do tych spraw, ale z jedną rzeczą w obecnej chwili pogodzić się nie potrafię. Nie wierzę, że dobry kod potrafi się sam w pełni opisać bez komentarzy. Dla mnie bardzo ważne jest, żeby w nagłówku opisane były w komentarzu przed metodą czy polem wszystkie ważne informacje, takie jak:
W jakim zakresie mogą być parametry (np. koniecznie 0.0f .. 1.0f).
W jakich jednostkach mają być parametry (np. w radianach na sekundę).
Jakie wartości specjalne mogą przyjmować parametry (np. 0, MAXINT).
Które wskaźniki mogą, a które nie mogą być puste (NULL).
Co oznaczają parametry (wolę to napisać w komentarzu, niż bufować 30-znakowy identyfikator).
Czas życia - kiedy obiekt pod wskaźnikiem istnieje.
Kiedy danej metody wolno używać.
Ale programista uczy się przez całe życie. Za kilka miesięcy będę się pewnie wstydził tej notki :)
