Wskazówki dotyczące pisania komentarzy
- Zamiast komentować zły kod, lepiej przepisać go na nowo!
Czytelny kod najczęściej nie wymaga komentarzy! I nie należy tu sugerować się wskazówką dla prawdziwych programistów, którzy nie komentują swojego kodu:
Real Programmers don't comment their code. If it was hard to write, it should be hard to understand.
Let your code document itself! - Jeśli w kodzie występują jakieś stałe, które nie są oczywiste, warto napisać co one oznaczają.
- Fragmenty programu działające wg określonego algorytmu, warto opisać krótko wyjaśniając powody zastosowania takiego, a nie innego algorytmu (w przypadku jeśli sam kod nie jest w stanie tego wyjaśnić).
The code should explain how. The comments should explain why. - W miejscach niedokończonych, warto zostawić komentarz: /* TODO: opis co należy dopisać */.
- NIE należy pozostawiać zakomentowanego kodu, zamiast tego warto użyć systemu wersjonowania zmian, np. Git, CVS czy SVN.
Są jednak inne rodzaje komentarzy, które nie muszą odnosić się do powyższych wskazówek:
- Komentarze prawne - dotyczące licencji oprogramowania, właściciela pliku, praw autorskich, itp.
- Komentarze dokumentacyjne - służące do wygenerowania dokumentacji dla projektu (więcej: Komentowanie i estetyka kodu).