Hallo,
hat jemand von euch eine Art Dokumentationsleitfaden für Software parat? Am besten natürlich noch von einer Uni oder TH.
Mein Kunde meint eine Dokumentation benötige nur sporadische inline-Kommentare und keine zusätzlichen Dokumente wie z.B. unter
http://mata.gia.rwth-aachen.de/Vortraege/Juergen_A_Lamers/Dokumentation/GIADokuRichtlinie/script/node4.html aufgeführt.
Wäre für Quellen für gute Gegenargumente dankbar! :)
Wäre für Quellen für gute Gegenargumente dankbar! :)
"Aha, und wer soll das dann warten? Ich sicher nicht." – Ich
Es gibt da ein paar Extremistische Programmierer, die denken, dass es ausreicht, wenn Software selbstdokumentierend ist, d.h. der Quellcode gut zu lesen ist. Diese Gruppe behauptet weiterhin, dass Kommentare nutzlos seien, da der Quellcode ja ausreichen sollte, um das Programm zu lesen. Zuguterletzt behaupten diese, dass eine separate Dokumentation schädlich ist, da diese gewartet werden muss. Es reicht ja, wenn genügend Unittests vorhanden sind um zu verhindern, dass unnötige Veränderungen entstehen.
Die übliche Gegenargumentation lautet, dass ein neuer Programmierer sich einen Überblick über das Programm verschaffen muss. Dafür halte ich die von dir aufgeführte URL für maßlos übertrieben, aber ein separates Dokument durchaus für nötig. Innerhalb des Programms sollten Kommentare eigentlich nur zu jeder Funktion/jeder Methode/jedem Objekt gegeben werden, damit man sich innerhalb des Quellcodes zurechtfindet. Wenn komplizierte Codefragmente innerhalb einer Funktion auftreten, die man unbedingt kommentieren möchte, sollte man erst prüfen, ob diese sich nicht besser in einer eigenen Funktion kapseln lassen.
Quellen gibt es dazu wie Sand am Meer, und jeder behauptet was anderes. Da es sich hierbei um praktisch reine Geschmackssache handelt, wirst du mehr Flamewars als sonstwas finden.
Du meinst eine Entwicklerdokumentation? Das ist dann, wenn man es richtig macht, ein Nachschlagewerk für Konzepte hinter Klassengruppen, Konventionen oder auch Tips und Tricks.
Manche Umsetzungen lassen sich nicht ohne Weiteres mit Quelltextkommentar erschlagen.
Stell Dir ein Automobil als Projekt vor und Mechaniker könnten von einem Bauteil nur Typ, Funktion und so weiter erfahren, indem sie es aufflexen und kleine Zettelchen darin durchstöbern.
Wenn Du nur 30 Klassen oder so hast, die nicht viel machen, kannst Du Dich eigentlich komplett auf den Quelltextkommentar stützen.
Bei 600 Klassen, einem eingegliederten Framework, diversen benutzten Third-Party-Modulen und wirtschaftswissenschaftlichen Spezial-Rechentools fällt man hingegen schnell mal auf die Fresse mit solch einer Mentalität ;)
Was Anarch zu Deinem verlinkten Leitfaden gesagt hat, kann ich allerdings nur unterstützen ;) So ein formaler Ansatz macht erst bei Projekten ab 30 Mannjahren und einer hohen Mitarbeiterfluktuation Sinn.
Du meinst eine Entwicklerdokumentation?
Ich hoffe doch - wenn der verlinkte Leitfaden eine Benutzerdokumentation sein soll, wird mir übel :-)
Manche Umsetzungen lassen sich nicht ohne Weiteres mit Quelltextkommentar erschlagen.
Ja. Je größer das Projekt, desto sinnvoller ist eine Einführung in einer separaten Dokumentation.
Die Dokumentation sollte aber das Lesen von Quellcode (und dessen Kommentaren) nicht
ersetzen, dadurch erhält man zu viele Redundanzen, die vorrangig die Dokumentation schnell veralten lassen.
Das ganze eXtrem zu sehen und gar keine Dokumentation mehr zu wollen, halte ich auch für nicht sonderlich sinnvoll.
Stell Dir ein Automobil als Projekt vor und Mechaniker könnten von einem Bauteil nur Typ, Funktion und so weiter erfahren, indem sie es aufflexen und kleine Zettelchen darin durchstöbern.
Wenn du schon einen schiefen Vergleich wählst: Der Quellcode entspricht dem Bauplan, nicht dem fertigen Auto. Es ist auch hier nicht sinnvoll, das gleiche im Bauplan und in der Beschreibung stehen zu haben. Die Beschreibung soll eben einen Überblick über den Bauplan geben.
Was Anarch zu Deinem verlinkten Leitfaden gesagt hat, kann ich allerdings nur unterstützen ;) So ein formaler Ansatz macht erst bei Projekten ab 30 Mannjahren und einer hohen Mitarbeiterfluktuation Sinn.
Selbst da wirst du feststellen, dass so eine Dokumentation nach drei Wochen derart veraltet ist, dass man sie eigentlich komplett neu schreiben müsste. Das wird bei solchen Projekten dann gerne vor einem Release nochmal schnell nachgeholt, was den Releaseprozess gerne noch etwas verzögert.
Aber wie gesagt: Das ist eigentlich derartig Geschmackssache, dass wir uns jetzt theoretisch die Köpfe noch drei Jahre lang darüber einschlagen könnten, ohne auch nur eine einige Dokumentation darüber geschrieben zu haben :-)
