Codedokumentation zuerst? [geschlossen]

Hat jemand jemals versucht, zuerst eine vollständige Codedokumentation zu erstellen, bevor er den Code tatsächlich schrieb? Ich habe früher darüber nachgedacht, weil ich dachte, es würde helfen, eine konkrete Schnittstelle zu schreiben und sicherzustellen, dass Ihr ursprüngliches Design nicht auf dem Boden liegt, indem Sie darüber nachdenken, wie Klassen interagieren. Ist das eine gute Idee? Hat es jemand versucht? Ell

Ja.

Sie denken darüber nach, was genau Ihr Code tun soll. Die Idee ist, dass Sie mit jedem Teil des Codes beginnen und genau wissen, was zu tun ist, um dieses Modul zu vervollständigen.

Es ist auch einfacher, etwas auf dem Zeichenbrett zu reparieren als in der IDE.

Es gibt zwei Arten, darüber nachzudenken:

1) Dokumentation wie in Word-Dokumenten, Wiki usw. Per Definition können Sie keine vollständige Codedokumentation haben, da Sie keinen Code zum Dokumentieren haben. Sie können zunächst versuchen, hochgradiges Design, Annahmen, Schnittstellen und Verträge zu dokumentieren.

2) Dokumentation als ausführbare Tests. Es gibt eine Denkschule, die besagt, dass ausführbare Komponententests die beste Dokumentation sind. Diese Denkschule befürwortet auch diese Art von Dokumentation, bevor der Code (TDD) geschrieben wird. Gleichzeitig schreiben Sie nicht von Anfang an alle Tests für das gesamte System. Sie teilen es zuerst nach Anwendungsfällen auf, dann führen Sie Tests und Code pro Anwendungsfall durch.

Beginnend mit der Dokumentation handelt es sich um ein klassisches Wasserfallmodell, das alle mit diesem Modell verbundenen Fallstricke aufweist. Je mehr Sie dokumentieren, desto mehr müssen Sie aktualisieren, wenn sich die Anforderungen ändern. Ein Vorteil des Einstiegs in die Benutzerdokumentation besteht darin, dass Sie möglicherweise früher Feedback (und damit Änderungen) erhalten. Die Erfahrung zeigt jedoch, dass die meisten Menschen schlecht darin sind, Dokumentation mental auf Aktionen abzubilden. Daher verwenden wir stattdessen Prototypen, mit denen die Benutzer die Software tatsächlich verwenden und auf diese Weise Feedback geben können.

Eine Variation von "Dokumentation zuerst" ist die gebildete Programmierung . Schreiben Sie zunächst eine Beschreibung der Funktionsweise des Programms aus Sicht des Programmierers. Passen Sie das weiter an, bis es kompiliert ist. Voila, ein Alphabetisierungsprogramm.

Ich persönlich finde es besser, Diagramme (wie UML) zu verwenden, um eine einfache Modellierung durchzuführen und den Fluss der Dinge zu zeigen. Dies ist viel schneller als das Dokumentieren von Dingen in Worten und kann, wenn es richtig gemacht wird, genauso beschreibend sein. Ich würde jedoch zögern, eine vollständige Dokumentation zu erstellen, da ich persönlich noch nie ein Projekt hatte, an dem ich gearbeitet habe und das sich im Laufe der Programmierung nicht geändert hat.

BEARBEITEN: Einige Dokumentationen sollten jedoch im Laufe der Zeit durchgeführt werden. Dies erleichtert die spätere vollständige Dokumentation.

Joshua Bloch diskutiert genau diesen Punkt in seinem Interview für das Buch "Coders at Work".

Im Gegensatz zu eher orthodoxen und akademischen Ansichten rät er etwas nach Ihren Wünschen (vielleicht haben Sie es dort selbst gelesen?): Bevor Sie die Dokumentation schreiben, müssen Sie verstehen, was Sie vom System wollen, und eine "realere" bekommen "Gefühl. Zu diesem Zweck entwarf er einen Teil der Schnittstellen und einen Clientcode, der sie verwendet.

Das Wichtigste ist zu wissen, was Sie bauen möchten: welches Problem Sie lösen möchten. Die Bedeutung der Anforderungsanalyse kann nicht genug betont werden. Es gibt Leute, die denken: „Oh ja, Anforderungsanalyse; Sie gehen zu Ihrem Kunden und sagen: "Was brauchen Sie?" Er sagt es dir und du bist fertig. “

Nichts ist weiter von der Wahrheit entfernt. Es ist nicht nur eine Verhandlung, sondern auch ein Prozess des Verstehens. Viele Kunden werden Ihnen kein Problem mitteilen. Sie werden Ihnen eine Lösung sagen. Ein Kunde könnte beispielsweise sagen: „Sie müssen diesem System Unterstützung für die folgenden 17 Attribute hinzufügen. Dann müssen Sie fragen: „Warum? Was machst du mit dem System? Wie erwarten Sie, dass es sich entwickelt? '”Und so weiter. Sie gehen hin und her, bis Sie herausgefunden haben, wozu der Kunde die Software wirklich braucht. Dies sind die Anwendungsfälle.

In dieser Phase ist es das Wichtigste, eine Reihe guter Anwendungsfälle zu entwickeln. Sobald Sie das haben, haben Sie einen Benchmark, an dem Sie jede mögliche Lösung messen können. Es ist in Ordnung, wenn Sie viel Zeit damit verbringen, es einigermaßen richtig zu machen, denn wenn Sie es falsch verstehen, sind Sie bereits tot. Der Rest des Prozesses wird eine Übung der Sinnlosigkeit sein.

Das Schlimmste, was Sie tun können - und ich habe gesehen, dass dies passiert - ist, dass Sie ein paar kluge Kerle in einen Raum bringen, um sechs Monate lang zu arbeiten und eine 247-seitige Systemspezifikation zu schreiben, bevor sie wirklich verstehen, was sie sind versuchen zu bauen. Denn nach sechs Monaten haben sie ein sehr genau spezifiziertes System, das möglicherweise unbrauchbar ist. Und oft sagen sie: "Wir haben so viel in die Spezifikation investiert, dass wir sie bauen müssen." Also bauen sie das nutzlose System und es wird nie benutzt. Und das ist schrecklich. Wenn Sie keine Anwendungsfälle haben, erstellen Sie das Ding und versuchen dann, etwas sehr Einfaches zu tun, und Sie erkennen, dass: „Oh mein Gott, um etwas sehr Einfaches zu tun, wie ein XML-Dokument zu nehmen und es zu drucken, sind Seiten für Seiten erforderlich Code." Und das ist eine schreckliche Sache.

- Joshua Bloch, aus einem Interview in " Coders at Work: Reflexionen über das Handwerk der Programmierung " von Peter Seibel

Wenn Sie bereits in diese Richtung denken, wäre es gut, wenn Sie das Buch in die Hand nehmen und das gesamte Interview lesen könnten. Wie gesagt, er ist immer sehr aufschlussreich.

Einige Leute gehen sogar noch weiter und sagen, dass ein Unternehmen vollständig rückwärts arbeiten sollte

1. Schreiben Sie die Pressemitteilung
2. Schreibe eine FAQ
3. Definieren Sie das Kundenerlebnis
4. Schreiben Sie das Benutzerhandbuch
5. Starten Sie die Programmierung

Siehe http://www.allthingsdistributed.com/2006/11/working_backwards.html

Das Schreiben der vollständigen Codedokumentation zuerst ist wahrscheinlich übertrieben und erinnert ein wenig an die Wasserfallmethode. Ich habe jedoch festgestellt, dass ein pragmatischerer Ansatz darin besteht, zuerst die README zu schreiben . Hier ist der Grund:

Die README-Datei dokumentiert nicht jedes Detail Ihres Projekts. Stattdessen enthält es normalerweise die folgenden Informationen:

1. Beschreibung : kurzes "Verkaufsgespräch". Sagen Sie dem Leser, warum er weiterlesen soll.
2. Kurze Beispiele : Kurzcode-Schnipsel oder Screenshots zur Unterstützung der Beschreibung.
3. Schnellstart : Erste Schritte, Installationsanweisungen und weitere Beispiele.
4. Weitere Dokumentation : Links zu den vollständigen Dokumenten und weitere Informationen.
5. Projektorganisation : Wer sind die Autoren, wie kann man einen Beitrag leisten, wie kann man Fehler melden?
6. Rechtliche Hinweise : Lizenz, Urheberrecht und sonstige rechtliche Details.

Wenn ich das "Verkaufsgespräch" im Voraus schreibe, muss ich mir ganz klar darüber sein, warum dieses Projekt existieren sollte und warum Entwickler es verwenden sollten. Das bloße Schreiben vollständiger Sätze zur Beschreibung des Projekts ändert es oft zum Besseren: Sie verstehen es besser, entwickeln neue Ideen und decken potenzielle Probleme auf. Es ist auch ein großartiges Priorisierungstool: Alles im "Verkaufsgespräch" ist ein Muss!

Die "Kurzbeispiele" und die "Kurzanleitung" zwingen mich, die wichtigsten Anwendungsfälle aus der Sicht des Benutzers zu durchdenken. Ich habe festgestellt, dass dies vor dem Schreiben von Code - bevor die Implementierungsdetails und engen Fristen festgefahren sind - zu viel saubereren APIs und Designs führt. Denken Sie daran: Programme sollten so geschrieben werden, dass sie gelesen werden können, und nur im Übrigen, damit Maschinen ausgeführt werden können ( SICP ).

In "Weitere Dokumentation" erstelle ich einen Überblick über die Teile, für die eine detaillierte Dokumentation erforderlich ist, die später durchgeführt werden soll. Mit "Projektorganisation" kann ich herausfinden, wer an dem Projekt und den Codierungspraktiken arbeiten wird. "Rechtliche Hinweise" ... nun, kann diese auch aus dem Weg räumen.

Sobald Sie diese grundlegende README-Datei eingerichtet haben, verfügen Sie über ein Dokument, das für Diskussionen, Entwurfsprüfungen, Aufteilung der Arbeit und Projektplanung nützlich ist. Überprüfen Sie während der Arbeit am Projekt regelmäßig die README-Datei, um sicherzustellen, dass Sie immer noch auf dem richtigen Weg sind. Wenn Sie die README-Datei und die "weitere Dokumentation" schrittweise aktualisieren, bedeutet dies, dass Ihre gesamte Dokumentation fertig ist, wenn der Code fertig ist. Dies ist eine viel angenehmere Erfahrung, als alles in letzter Minute zu dokumentieren.

Weitere Informationen finden Sie unter:

1. Readme-gesteuerte Entwicklung
2. Der wichtigste Code ist kein Code
3. Sie sind das, was Sie dokumentieren

Warum möchten Sie nicht darüber nachdenken, wie Klassen interagieren? Warum ist das eine schlechte Sache? Ich denke tatsächlich über die Interaktionen nach, bevor ich überhaupt weiß, was die Klassen sind. Auf diese Weise identifizieren sich die Klassen.

Sie sollten eine Vorstellung davon haben, was Sie vorhaben, bevor Sie den Code schreiben. Die Frage ist immer, wie Sie das, was Sie codiert haben, mit dem, was Sie geschrieben haben, synchron halten können. Einige sagen, versuchen Sie es nicht, andere sagen, vergessen Sie die ursprünglichen Dokumente und halten Sie die Kommentare aufrecht. Natürlich ist der Code immer die kanonische Quelle. Es stellt sich dann die Frage, ob es sich lohnt, zu dokumentieren, was der Code für diejenigen tut, die später kommen oder den Code verwenden. Jeder kann herausfinden, was eine Funktion tut. Die Aufgabe des Autors ist es, jemandem zu helfen, in 5 Minuten zu verstehen, was jeder in einer Stunde herausfinden kann. Addiere die Deltas und bestimme deinen Weg.