Ein fertiges Stück Software. Und dann?

[Stephan (Gast)]

Hallo!

Angenommen eine kleine Firma strebt zu Eigenentwicklungen, die µC 
beinhalten, sprich, es entsteht Code.
Gibt es einen Standard, wie Code dokumentiert wird? Wird jede Funktion 
und jede Prozedur womöglich auf dem Papier beschrieben?

[Stephan (Gast)]

EDIT:
Dokumentiert und Archiviert

[Dirk B. (dirkb2)]

Mit einer Versionsverwaltung und z.b Doxygen.

Auf dem Papier eher nicht mehr, aber als html oder pdf.

[Axel S. (a-za-z0-9)]

Stephan schrieb:
> Gibt es einen Standard, wie Code dokumentiert wird? Wird jede Funktion
> und jede Prozedur womöglich auf dem Papier beschrieben?

Dokumentiert wird weniger der Code als solcher, sondern vor allem die 
Schnittstellen. Also z.B. für jede Funktion die Bedeutung und der 
erlaubte Wertebereich der Funktionsparameter und Bedeutung und Werte- 
bereich des Rückgabewertes. Für diese Art Dokumentation hat es sich 
weitgehend durchgesetzt, magische Kommentare in den Code zu schreiben 
und die mit Tools wie javadoc, Doxygen etc. zu extrahieren und 
formatieren.

Diese Art Dokumentation sollte bevorzugt im Code stehen, weil man nur 
dann überhaupt eine Chance hat, daß Code und Dokumentation 
übereinstimmen. Denn schlimmer als fehlende Dokumentation ist falsche 
Dokumentation.

Gute Dokumentation erkennt man daran, daß sie nicht das offensicht- 
liche wiederholt. Wenn ein Funktionsparameter z.B. vom Typ unsigned 
int ist, dann braucht die Dokumentation nicht nochmal zu sagen, daß 
das eine vorzeichenlose Ganzzahl ist. Ebenso müßte man für eine Methode

class foo {
   int save_to_disk(char* filename);
}

nicht extra betonen, daß die ein foo-Objekt in einer Datei mit Namen 
filename abspeichert. Statt dessen könnte man sich vielleicht darüber 
auslassen, welches Fileformat das ist (evtl. nur ein Pointer auf andere 
Dokumentation). Und man verliert besser ein paar Worte, wie lang der 
Filename sein darf, mit welchen Rechten die Datei angelegt wird, was der 
Rückgabewert bedeutet usw. usf.

Man sollte sich auch vorher klar sein, wozu die Dokumentation später 
mal dienen soll. Bei Kundenentwicklungen wird der Kunde diese Art 
Dokumentation vielleicht gar nicht brauchen. Aber wenn dein 
Softwareentwickler vom Bus überfahren wird, braucht sein Nachfolger 
vielleicht diese Doku. Oder wenn 10 Jahre später der Kunde wiederkommt 
und Wünsche nach Erweiterung der Software hat, ist so eine Doku auch 
hilfreich.


XL

[Kein Name (Gast)]

Wie in der Realität dokumentiert wird, kannst du z.B bei 
geek-and-poke.com nachlesen.

Habe noch nie erlebt, dass die Dokumentation zu dem passt, was wirklich 
gemacht wurde. Jeder Enwickler weiß - Doku ignorieren und gleich die 
Leute fragen, die das damals gemacht heben.