Wie Methoden kommentieren und dokumentieren

[bowo]

Also das man Quelltext dokumentiert und kommentiert ist mir klar.

Ich mache es ja auch selbst, sonst blickt keiner mehr durch.

Nur eine Frage:

Gibt es eine Art Richtlinie oder gewisse Beschreibungen wie eine dokumentation einer Methode auszusehen hat?

Gibts es link zu Tutorials oä ?

[Crush]

Es gibt praktisch für alles Richtlinien - und bei Computern zählt vor allem die IEEE-Norm (www.IEEE.org)

Es zeigt sich aber, daß jeder auch bei der Dokumentation dazu neigt einen eigenen Stil zu entwickeln (oder auch gar Keinen) und deshalb sollte man sich an die Kollegen halten, weil die später vielleicht durch den eigenen Code halblebig durchblicken sollten.

Damit Software auf ein gewisses standardisiertes Niveau kommt gibt es sogar schon einen hinter Vorgehaltenen Pseudo-Standard für Softwareentwicklung unter ISO-Norm (noch nicht komplett abgesegnet, vielleicht jetzt schon, aber eigentlich sind sich scheint´s alle einig):

"Die DIN EN ISO 9001 für Klein- und Mittelbetriebe"

Beim BHV-Verlag habe ich mir mal ein Buch welches die Richtung für die Softwareentwicklung andeutet gekauft: "Der individuelle Software-Prozess" aus der advanced edition ISBN 3-89360-957-1 (www.bhv.net)

Soweit ich weiß haben diese Norm die größeren Industriebetriebe sich selber aufgrund der DIN ISO 9001 aufgestellt und beantragt diese abzusegnen. Aber auch hier wird vor allem das Hauptaugenmerk auf die Qualitätssicherung bei Softwareprodukten gelegt und sooo detailliert gerade die Ausdokumentierung von C++-Methoden nun auch wieder nicht aufgedeckt. Die gehen nach dem Metto: Das Ziel ist der Weg!

[mst]

Dafür gibt es eigentlich keine feste Richtlinie, aber einige Dinge sind für eine Methoden-Dokumentation sehr nützlich:

- Name der Methode

- Beschreibung/Was tut die Methode

- Beschreibung der Einzelnen Parameter

- Beschreibung des Rückgabewertes

(z.B. hiesst "0" erfolgreich oder fehlerhaft)

- Es können auch noch Vorbedingungen und Nachbedingungen angegeben werden.

Insgesamt ähneln sich ja die bekannten Dokumentationen von Funktionen/Methoden.

Man könnte ja auch z.B. den ungefähren Aufbau einer MSDN-Funktion als Vorbild nehmen.

Gruß

mst