Der häufigste Fehler in Dokumentationen (abgesehen von deren Fehlen) ist, daß die Wiederholung von offensichtlichem Quelltext, so wie in diesem trivialen (aber ärgerlich häufigen) Beispiel:

# Increment i.
incr i

Eine Dokumentation sollte Informationen auf einer höheren Ebene über die allgemeine Funktion des Quelltextes enthalten, um dem Leser zu helfen, die Bedeutung einer koplizierte Ansammlung von Anweisungen zu verstehen. Z.B. der Kommentar

# Probe into the array to see if the symbol exists.

ist gleichsam hilfreicher als

# Loop through every array index, get the third value of the
# list in the content to determine if it has the symbol we are
# looking for. Set the result to the symbol if we find it.

Alles in diesem zweiten Kommentar is wahrscheinlich offensichtlich aus dem darauffolgenden Quelltext.

Eine andere Sache, die es zu beachten gilt, ist die Wortwahl. Verwende andere Worte im Kommentar, als diejenigen die in Variablen- ider Prozedurnamen auftreten. So ist z.B. der Kommentar

# SwapPanels --
#
# Swap the panels.
# ...

nicht sehr nützlich. Der gesamte Kommentar ist bereits durch den Prozedurname offensichtlich. Hier ist ein nützlicherer Kommentar:

# SwapPanels --
#
# Unmap the current UI panel from the parent frame and replace
# it with the newly specified frame. Make sure that the new
# panel fits into the old frame and resize if needed.
# ...

Dieser Kommentar sagt, warum man diese Prozedur wohl verwenden könnte, zusätzlich zu der eigentlichen Aufgabe, was den Kommentar wesentlich nützlicher macht.