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?
Mit einer Versionsverwaltung und z.b Doxygen. Auf dem Papier eher nicht mehr, aber als html oder pdf.
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
1 | class foo { |
2 | int save_to_disk(char* filename); |
3 | }
|
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
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.
Bitte melde dich an um einen Beitrag zu schreiben. Anmeldung ist kostenlos und dauert nur eine Minute.
Bestehender Account
Schon ein Account bei Google/GoogleMail? Keine Anmeldung erforderlich!
Mit Google-Account einloggen
Mit Google-Account einloggen
Noch kein Account? Hier anmelden.