vorgefertigte Skripte, sicherheits lücke?

[Der Martin]

Hallo,

Aber mal im Ernst, Dokumentieren ist eine Kunst, die noch weniger beherrscht wird als das Programmieren.

das ist leider wahr.

Man muss ja in den Kommentaren nicht das Offensichtliche beschreiben, sondern was man sich dabei gedacht hat, warum man die Lösung so implementiert hat und nicht doch anders, womöglich noch abweichend vom Üblichen.

ACK. Das A und O beim Dokumentieren ist nicht, zu beschreiben, WAS der Code tut, sondern WARUM. Dazu gehören, wie du schon sagst, ein paar Worte dazu, was man sich als Programmierer bei dieser konkreten Implementierung gedacht hat, aber auch Zusammenhänge - etwa das gewünschte Zusammenspiel verschiedener Funktionen oder Objekte.
Genau das vermisse ich auch oft in Dokumentationen "professioneller" Bibliotheken und Frameworks: Da wird jedes einzelne Element, jedes API genau beschrieben, aber der Zusammenhang existiert oft nur in den Köpfen der Programmierer.

Und das gilt IMO sowohl für Kommentare im Code, als auch für eine eigenständige Dokumentation.

Ciao,
 Martin