Benutzt jemand das überhaupt produktiv?
Es kommt sehr stark auf die Art der Software und die Zielgruppe an, ob es sich überhaupt lohnt
eine Dokumentation aus den Kommentaren im Sourceccode generieren zu lassen.
IMHO muss folgende Bedingung zutreffen:
* beim Sourcecode handelt es sich um eine Klassenbibliothek, die auch von anderen Programmierern ausserhalb des eigenen Teams benützt werden soll
Wenn die Doku nur für eigene Zwecke generiert werden soll, dann verursachen die Kommentare mehr Schaden als Nutzen.
1.) die Pflege der Kommentare braucht viel Zeit
2.) der Programmierer, der den Sourcecode erstellt hat, benötigt keine Doku von jeder Klasse, Methode und Property.
Man braucht nur an manchen Stellen etwas Hilfe in Form von Kommentaren um zu verstehen, was man vor 2 Jahren da verbrochen hat
3.) die Kommentierung von Parametern, Returnwerten, usw. für jede Methode behindern die Weiterentwicklung.
Nur weil die Kommentare da sind, hat der Programmierer einen unbewussten mentale Widerstand die Parameter oder die Methodennamen zu verändern.
Das
Refakturieren wird behindert.
Früher wurde z.B. in meinem Team vor jede Funktion oder Methode folgender Kommentar gesetzt:
Delphi-Quellcode:
{************************************************
* Name: XYZ
* Descr.: ............
* Params: ....
* Return: [none]
* Created: 01.01.2005/User
* Changed: 01.01.2005/User
************************************************}
function XYZ(....)
begin
end;
Was für eine Zeitverschwendung!!
Die Kommentare waren meistens unvollständig, manchmal auch falsch weil sich Parameter und/oder Returnwert geändert haben.
Dann lieber keine Kommentare als so ein visuelles Störfeuer.
Heute sehen meine Kommentare z.B. so aus:
Delphi-Quellcode:
// alle Zeichen <#32 oder >#128 entfernen
function RemoveInvalidChars(const s:string):string;
Ich hoffe mal, dass ich hier keine kontroversen Diskussionen auslöse wie man Sourcecode kommentieren soll!