PHP Coding Standard

Das PEAR-Projekt dokumentiert sehr ausführlich auch einzelne Variablen:

   /**
    * Should data manipulation queries be committed automatically?
    * @var bool
    * @access private
    */
   var $autocommit = true;

Man kann sich sehr leicht vorstellen, dass eine solche Verfahrensweise sehr viel Arbeit macht und es für jede Zeile auch übertrieben wäre. Systemkritische Variablen und Konstanten sollten aber auf diese Art und Weise dokumentiert werden.

   $boolean = ($i > $j);   // IF $i > $j: $boolean becomes TRUE or FALSE

Denken Sie bei Kommentaren an die lesende Zielgruppe, aber ein wenig Fachwissen kann ruhig vorausgesetzt werden. Wenn also die Zeile
$boolean = ($i > $j);
in Ihrem Team jeder versteht, lassen Sie den Kommentar weg.

Der C++ Coding Standard spricht von strategischen oder taktischen Kommentaren. Ein strategischer Kommentar beschreibt eine Funktion oder einen ganzen Absatz des Source-Codes. Ein strategischer Kommentar wird vor dem Code plaziert.
Ein taktischer Kommentar beschreibt eine bestimmte Zeile und wird - wenn möglich - ans Ende der Zeile (also hinter dem Code) plaziert. Auch wenn der Kommentar ohne den Code nicht sinnvoll ist, sollte man einen taktischen Kommentar verwenden.

Die Meinungen über die Art, die Menge und andere Faktoren der Dokumentation gehen stark auseinander. Die einen finden zu viele taktischen Kommentare unübersichtlich, die anderen denken, dass zwanzig Zeilen strategischer Kommentar für fünf Zeilen komplexen Source-Code gerade so ausreichend ist. Jedes Team muss also eine Entscheidung darüber fällen, in welchem Maße Kommentare angewendet werden.
Das Prinzip der Einfachheit sollte immer Anwendung finden. Das erklärte Ziel jeder Dokumentation und jedes Kommentars muss Transparenz und Verständnis für den Source-Code sein.

Zitat aus dem Film Philadelphia: "Bitte erklären sie mir das so, als ob ich sechs Jahre alt wäre!"
Natürlich ist es unmöglich, dass ein 6-jähriger den komplexen Source-Code eines großen Projektes versteht, aber ich kann nicht oft genug betonen, dass Teamwork, Kommunikation, Verständnis und Qualität des Source-Codes im Vordergrund jedes Projektes stehen müssen. Das Ziel von leicht verständlichem Source-Code ist erst erreicht, wenn jedes Mitglied des Teams, jedes Modul aus dem Stehgreif erklären kann.