Wskazówki dotyczące pisania komentarzy

  1. 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!
  2. Jeśli w kodzie występują jakieś stałe, które nie są oczywiste, warto napisać co one oznaczają.
  3. 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.
  4. W miejscach niedokończonych, warto zostawić komentarz: /* TODO: opis co należy dopisać */.
  5. 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:

  1. Komentarze prawne - dotyczące licencji oprogramowania, właściciela pliku, praw autorskich, itp.
  2. Komentarze dokumentacyjne - służące do wygenerowania dokumentacji dla projektu (więcej: Komentowanie i estetyka kodu).