Systeme entwickeln sich mit der Zeit. Wenn etwas an verschiedenen Stellen dokumentiert ist, wird es schwierig die Dokumentation auf dem aktuellen Stand zu halten, während sich das System weiterentwickelt. Stattdessen, versuche jede wichtige Entwurfsentscheidung genau an einer Stelle zu dokumentieren, und zwar so nah wie möglich an dem Quelltext, welcher die Entwurfsentscheidung implementiert. Die Hauptdokumentation für jede Prozedur gehört in den Prozedurkopf.

Es besteht keine Notwendigkeit, diese Information im Rumpf der Prozedur zu wiederholen (aber es mag zusätzliche Kommentare im Prozedurrumpf geben, welche Einzelheiten enthalten, die nicht im Prozedurkopf stehen). Wenn eine Bibliotheksprozedur gründlich in einem Handbuch dokumentiert ist, kann der Prozedurkopf spärlich ausfallen, indem man einfach auf den Eintrag im Handbuch verweist.

Die andere Seite dieser Medaille ist, daß jede wichtige Entwurfsentscheidung mindestens einmal dokumentiert werden muß. Wenn eine Entwurfsentscheidung an verschiedenen Stellen verwendet wird, wird es schwierig diese an einer zentralen Stelle zu dokumentieren. Versuche eine Datenstruktur oder Hauptprozedur zu finden, an welcher der Hauptteil der Dokumentation stehen kann; dann kann man auf diesen Teil aus den anderen Stellen heraus Bezug genommen werden. Wenn all dies nicht möglich ist, dann füge einen Kommentarblock am Anfang einer Datei, welche die Entwurfsentscheidung implementiert.

Anm. d. Übersetzers: Hat jemand eine bessere Übersetzung für "design decision", als Entwurfsentscheidung? Das klingt irgendwie nicht so gut!?!