Das wichtigste ist, dass Du überhaupt dokumentierst! Glaub mir, selbst große (und ich meine bundesweit wirklich große) Softwareunternehmen haben teilweise in dem Bereich noch echte Lücken. Sofern Du also pauschal überhaupt dokumentierst, und wenns nur Kommentare sind, ist das schonmal was.
Anders ausgerückt: Der Sinn von Dokumentation wird immer dann klar, wenn die Frage aufkommt: "warum macht dieser Teil des Codes das ganze genau so?" - insbesondere, wenn man anfängt, irgendwo einen Bug zu korrigieren. Deine Dokumentation muss darauf eine Antwort liefern.
Der einfachste Weg ist es, bei jeder Entscheidung, die im Projekt gefällt wird, das Anforderungsdokument zu aktualisieren. Es mag sich kleinlich anhören: aber es ist so unglaublich wichtig, dass Entscheidungen nicht irgendwo in PostIts oder College Blöcken verschwinden, sondern in die zentrale Dokumentation mit aufgeschrieben werden. Das ganze kann soweit gehen, dass man sagt: Code wird erst angefasst, wenn die Dokumentation fertig ist. Dies zwingt einen Entwickler, sich Gedanken zu machen, was er später entwickelt. Ich persönlich würde das ganze allerdings nicht so krass formulieren, schließlich ist Implementierung immernoch ein kreativer Prozess, in dem die meisten Problemstellungen von alleine gelöst werden - ich entwickle gerne zuerst, und ziehe die Dokumentation dann nach. Allerdings würde ich hierbei vorher ein grobes Design erstellen, wie vorzugehen ist. Das fällt dann aber eher in die Kategorie "Wegwerfdokumentation" - also Gekritzel mit Papier und Bleistift.
So spontan würde ich sagen, sind folgende Dinge wichtig als Grundlage:
* Ein Software-Enwicklungsprozess
Hier gibt es verschiedene Ansätze: von klassischen Modellen bis hin zu etwas "kreativeren" Ansätzen wie SCRUM oder so. Die Kernfrage, so wie ich das sehe, ist, was steht im Vordergrund: die Dokumentation, oder der Code?
Klassische Ansätze werden immer sehr viel Dokumentation mit sich ziehen. Alternative Ansätze werden eher den Code in den Vordergrund bringen.
Wir fahren einen eher klassischen Ansatz.
* Coderichtlinien
Die Frage hierbei ist, wie weit der Code sich selbst dokumentieren soll (also Kommentierung). Es gibt ja durchaus Modelle, in denen z.B. JavaDoc genutzt wird, um am Ende eine HTML-Dokumentation zu erzeugen, aber in Aktion habe ich das auch noch nicht gesehen, außer bei der Java-Bibliothek selbst - und die haben sich nicht um Fachlichkeiten zu kümmern. Ich würde in sofern fachliche Dokumentierung aus dem Code heraushalten, und nur technische Details dort dokumentieren (Hintergedanke: dies interessiert den Kunden eh nicht, und der Entwickler hat ja den Quellcode -- es macht also wenig Sinn daraus ein Dokument zu erzeugen). Ein Funktionskommentar enthält also nur Informationen darüber, WIE etwas gemacht wird. WAS fachlich passiert, muss der Entwickler wissen, bevor er in den Code schaut. Wir trennen also bewusst Kommentierung von weiterführender Dokumentation, wie Word-Dokumenten. Nichts destotrotz wird natürlich JEDE Funktion kommentiert, bekommt ein Review, etc.
Wir entwickeln in einem eher klassischen Modell, welches jedoch abgespeckt ist - wir schreiben keine Bedienungsanleitungen, und trennen auch nicht klassisch nach Lasten- und Pflichtenheft. Wir erstellen zuerst Anforderungsdokumente (recht kleine, formlose Word-Dokumente mit fachlichen Eckpunkten, Skizzen, etc.), und entwickeln danach ein "Fachkonzept", in dem die Anwendung bereits funktional vollständig dokumentiert wird (dies geht bereits auf die Ebene, wo welcher Button landet). Dieses Dokument hat auch der Kunde, ist also offiziell, und wird von jedem Entwickler gepflegt, der etwas ander Anwendung ändert. Darüber hinaus ist das Fachkonzept auch vollständig, was dort drinsteht, ist gültig.
Dieses Vorgehen funktioniert natürlich nur, wenn die Anwendung noch halbwegs überschaubar ist (nicht > 10 Entwickler), man im Voraus in der Lage ist abzuschätzen, wie die Anwendung, die Masken, etc. später aussehen werden, und man sich mit seinem Kunden vernünftig unterhalten kann (dieser also einen Fachbereich hat, der weiß, was er will!). Andere Situationen mag ich mir aber auch nicht wirklich vorstellen^^
Test-Dokumentation habe ich hierbei jetzt mal außen vorgelassen - das ist ein recht schwieriges Thema. Wir fahren hier ein Modell mit recht aufwändigen Testplänen und Testphasen, welches jedoch meiner Meinung nach zu aufwändig ist, weswegen ich dazu nichts sagen möchte. Gänzlich ohne wird es aber kaum gehen, denn so toll einige Leute JUnit finden, es liefert nur einen oberflächlichen Test der Fachlichkeit/Technik, und den auch nur mit ordentlichem Mehr-Aufwand bei der Entwicklung. Freitests o.ä. ersetzen solche Frameworks auch nicht, um Testpläne wird man nicht drumrum kommen.
