Zwar auf PHP bezogen, aber durchaus auch auf andere Programmiersprachen anwendbar (zumindest die welche ich kenne ): ein durchaus lesenswerter Artikel über das dokumentieren von Quelltext (Programmcode).

Nebst generellen Tipps für die Bezeichnungen von Elementen etc., geht der Artikel auch auf die automatische Erstellung einer PHP-Quelltext-Dokumentation mit dem phpDocumentor ein.

Wer sich mehr für die Anwendung des phpDocumentors und die verfügbaren Tags interessiert, dem möchte ich das Quickstart Tutorial zum phpDocumentor empfehlen.

Ich bin ein grosse Fan geworden von den von phpDocumentor verlangten Kommentar-Tags. Auch wenn ich ehrlich gesagt das Dokumentationstool noch nicht verwendet habe. Aber die Bezeichnungen von Funktionen, Variablen, etc. im Code macht eine Datei um einiges verständlicher (Achtung: auf eine einheitliche Struktur achten, sonst entsteht ein unübersichtliches Chaos).