Dokumentation aus Modellierung und Quelltext erstellen

[bgeltenpoth]

Hallo,
ich versuche gerade verzweifelt mit Delphi XE2 eine Projekt Dokumentation aus meinem Modell und den Kommentaren im Source Code zu generieren. Leider fehlen im HTML Output alle Kommentare die aus dem Quellcode kommen sollen.
Nach vielen Suchen bin ich auf dieses Thema gestoßen http://www.delphipraxis.net/80263-to...ommentare.html
Da das Thema schon auch mal so 6 Jahre alt ist, stellt sich die grossen Fragen:
Hat sich das mit Delphi XE2 verbessert?
Benutzt jemand das überhaupt produktiv?
funktioniert das überhaupt und gibt es irgendwo doch noch Dokumentation dazu?

Liebe Grüsse

Benedikt

[sx2008]

Zitat von bgeltenpoth:

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!

[Uwe Raabe]

Zitat von sx2008:

Ich hoffe mal, dass ich hier keine kontroversen Diskussionen auslöse wie man Sourcecode kommentieren soll!

Du hast zumindest schon mal den ersten Stein geworfen

Ich bin übrigens ganz deiner Meinung.

[bgeltenpoth]

Hallo,

Zitat:

beim Sourcecode handelt es sich um eine Klassenbibliothek, die auch von anderen Programmierern ausserhalb des eigenen Teams benützt werden soll

...das trifft leider nun ja gelegentlich mal zu (bei mir jedenfalls...)
grundsätzlich gebe ich euch ja recht, ABER: Eigentlich wollte ich wissen ob es funktioniert und ich etwas falsch verstanden habe oder ob ich mir erstmal keine weiteren Mühen machen muss.

Für jeden Erfahrungsbericht wäre ich also dankbar....