Hey,

also wenn auch andere Programmierer da dran gehen, die Funktionen dokumentieren. Schreibe in einer Zeile über einer Funktionssignatur 3 mal ' (das Zeichen für Kommentar), dann wird dir eine "Vorlage" reingemacht die du ausfüllen kannst.

etwa so:


Dazu dann ein Klassendiagram erstellen, siehe bei google. Wenn die GUI erklärt werden muss, könnte sie nicht intuitiv genug sein. Lässt sich nicht immer vermeiden, je nach komplexität des Programms.

Daraus Täte ich 2 PDF machen, Dev-Guide und User-Guide. DevGuide wichtige inofrmationen zur Nutzung, Klassendiagramm etc.. Die PDF für die User, da drin kann man die GUI erklären und oder evtl. CommandLine-Switches sofern vorhanden. Du kannst aber auch eine CHM Datei anlegen, das ist immer praktisch für Devs.

Man muss aber nicht alle Funktionen im Code dokumentieren, Function GetDatetime() as DateTIme, da ist der Name schon die Erklärung.

Achte darauf, nur das zu kommentieren, was im Code nicht selbstverständlich ersichtlich ist.
Bzw. schreibe code selbsterklärend. Bevor du etwas kommentierst, denke drüber nach, ob Code-Verbesserung den Kommentar nicht üflüssig machen könnte.
Soweit das Selbstverständliche.

Ansonsten sind es fast immer Konzepte und Prinzipien, die unterdokumentiert sind. Oder auch Geschäftsvorfälle - also was erreicht der User mit dem, was gecodet ist.

Ich mach zB gerne "FileHeader", also einen Bereich über der Code-Datei, wo ich manchmal ausschweifend fabuliere, was ich mir beim Code dieser Datei gedacht habe.
Guck zB in die Klassen WeakAttachBase rein, oder GraphAttach. Oder BinarySearcher CurrentTracking etc.
In diesen Files sind ungewöhnliche Konzepte umgesetzt - die muss man halt iwo aufschreiben.
Und die Konzepte ergeben erst im Zusammenspiel mehrerer Methoden einen Sinn, bzw funktionieren überhaupt.
Sowas kann man garnet in einer Methode dokumentieren.

Wie gesagt: Ansonsten im Code sind Kommentare immer auch störend, daher sehr kritisch den Nutzen abwägen.
Hingegen FileHeader stören nicht - die stehen über der Datei und kannste zuklappen, und können dann auch zugeklappt bleiben. (Im Gegensatz zu anderen Regions die meist Dinge verstecken, die man doch auch sehen muss.)
Noch einen Zacken ausschweifender können ReadMes ausfallen. Die beziehen sich dann auf mehrere Dateien, zB auf die Files in einem Ordner oder sowas..

Aber ich gebs ja zu: Grad meine Helpers sind reichlich unterdokumentiert.
(Aber immerhin: Da gibts durchaus auch ein paar FileHeaders mit was drin)

tragl schrieb:

damit im Notfall unsere IT weiterentwickeln oder Fehler ausbügeln kann

Hört sich schon fragwürdig an.