Wie viel Dokumentation ist genug?

Wie viel technische Dokumentation (für zukünftige Entwickler) reicht aus ? Gibt es ein angemessenes Verhältnis zwischen Stundencodierung und Dokumentationsstunden?

Papadimoulis meint, dass Sie sollten

die geringste Menge an Dokumentation zu erstellen, die benötigt wird, um das bestmögliche Verständnis zu ermöglichen,

Ist das eine gute Richtlinie, oder gibt es bestimmte Dinge, die ich erschaffen sollte?

Wie wäre es mit einem Flur-Usability-Test? Zeigen Sie den Code und die Dokumentation einem Entwickler, der mit dem Projekt nicht vertraut ist. Wenn Sie dies tun können, ohne den überwältigenden Drang zu haben, etwas zu erklären, während Sie den Code überprüfen, haben Sie genug.

Die Perfektion ist nicht nur ein Plus, sondern auch ein Plus für den Rentner.
Antoine de Saint-Exupéry

Ich habe eine Weile über dieses Thema nachgedacht.

Mein Fazit lautet: Es geht nicht um Quantität, sondern um Qualität und Kontext.

Zum Beispiel schlägt eine richtige Projektstruktur Kommentare, die erklären, wo sich die Dateien befinden (Implementierung vs. Intensität).

In ähnlicher Weise schlägt die Klassifizierung zur Verdeutlichung des Kontexts die Benennung (ID eines Patienten -> Patient.Id).

Ich glaube, dass DDD ein Mitspracherecht bei guter Dokumentation hat - Klassifizierung bietet Kontext, Kontext schafft Grenzen und Grenzen führen zu absichtlichen Implementierungen (hier gehört das hin, anstatt dass es existieren muss).

Code an sich ist nicht gut genug, um als Dokumentation zu gelten. Das Problem liegt in den meisten Fällen nicht darin, dass die Funktionsweise der Codes kommentiert oder nicht kommentiert wird, sondern darin, dass dies nicht die treibende Kraft (Domänenlogik) ist.

Wir vergessen manchmal, wer der Boss ist - wenn sich der Code ändert, sollte sich die Domänenlogik oder die Argumentation nicht ändern, aber wenn sich die Domänenlogik oder die Argumentation ändern, wird sich der Code definitiv ändern.

Konsistenz ist auch sehr wichtig - Konvention an sich ist nutzlos, wenn sie nicht konsistent ist.

Entwurfsmuster sind nicht nur „gute Praxis“ - es ist ein Jargon, den Entwickler verstehen sollten. Es ist verständlicher, einem Entwickler mitzuteilen, einer Factory einen neuen Typ hinzuzufügen, als einer Methode einen neuen Typ hinzuzufügen (wenn der Kontext und die Konsistenz schwach sind oder fehlen).

Der halbe Kampf ist Vertrautheit .

Nebenbei bemerkt, APIs, die eine Menge Dokumentation bevorzugen, sind auch sehr domänen- und kontextsensitiv. Manchmal ist das Duplizieren von Funktionen nicht böse (gleiche Sache, unterschiedliche Kontexte) und sollte als getrennt behandelt werden.

In Bezug auf das Kommentieren ist es immer gut, auf die Domänenlogik hinzuweisen, die hinter der Argumentation steht.

Zum Beispiel arbeiten Sie in der medizinischen Industrie. In Ihrer Methode schreiben Sie "IsPatientSecure = true;"

Jetzt kann jeder anständige Programmierer herausfinden, dass der Patient als sicher markiert ist. Aber wieso? Was sind die Implikationen?

In diesem Fall ist der Patient ein Insasse, der sicher in ein externes Krankenhaus gebracht wurde. Wenn man das weiß, kann man sich leichter vorstellen, welche Ereignisse bis zu diesem Punkt geführt haben (und was möglicherweise noch passieren muss).

Vielleicht scheint dieser Beitrag bestenfalls philosophisch zu sein - aber denken Sie daran, dass Sie über „Argumentation“ oder „Logik“ schreiben - nicht über Code.

Ich stimme dem Zitat von Papadimouslis zu. Der Quellcode kann für sich selbst sprechen, aber der Code kann Ihnen nicht sagen, warum er existiert, wie er verwendet werden soll und wie sich der Code verhalten soll.

Ich kenne kein gutes Verhältnis.

Ich habe Hunderte von Codezeilen mit sehr wenig Dokumentation geerbt. Es wurde schwierig für mich zu verstehen, warum der Code geschrieben wurde. Nachdem ich herausgefunden hatte, warum der Code geschrieben wurde, musste ich herausfinden, wie man den Code verwendet. Nachdem ich das herausgefunden hatte, musste ich verstehen, wie es sich verhalten soll, damit ich den Code unterstützen und warten kann.

Machen Sie Kommentare nur aus Erfahrung nicht zu spezifisch, da Sie sonst den eigentlichen Code UND die Dokumentation pflegen müssen. Es ist ein Albtraum, wenn die Dokumentation und der Code nicht synchron sind.

Genug, damit Sie aufhören, sich selbst zu erraten.

Wenn Sie zu irgendeinem Zeitpunkt während Ihrer Arbeit der Meinung sind, "hmm, vielleicht sollte ich das dokumentieren", machen Sie es einfach. Wenn Sie dann eine Dokumentation geschrieben haben und der Meinung sind, dass "ich das vielleicht näher erläutern sollte", machen Sie das weiter.

Spülen-wiederholen, bis dieses Gefühl verschwindet.

Ich habe festgestellt, dass ein risikogesteuerter Ansatz wie der in George Fairbanks Buch Just Enough Software Architecture vorgestellte sehr gut funktioniert, um zu verstehen, wie viel Dokumentation ausreicht. Sie können den Abschnitt lesen, in dem dieses Konzept vorgestellt wird (Kapitel 3), aber die Hauptidee ist:

• Drücken Sie die Dinge, die Sie über das "Systemverständnis" beunruhigen, als Risiken aus
• Priorisieren Sie die Risiken
• Reduzieren Sie die Risiken, bis Ihr Team das Gefühl hat, dass das Projektrisiko ausreichend reduziert wurde. In diesem Fall erstellen Sie wahrscheinlich eine Art Dokumentation.

Um Bedenken zu kalibrieren, damit Sie Risiken priorisieren können, hat es sich als hilfreich erwiesen, einige Ziele zu identifizieren, die als " Schwelle des Erfolgs" bezeichnet werden. Dies ist die Mindestanzahl von Zielen, die Ihr Team für ein "erfolgreiches" Projekt erreichen muss. Aus Dokumentationssicht könnte ein ToS-Beispiel so aussehen: "Ein Entwickler sollte in der Lage sein, innerhalb von 4 Stunden nach dem ersten Aufrufen des Frameworks ein einfaches Plug-In zu erstellen."

Identifizieren Sie nun einige Risiken. Mit dem System, das Sie gebaut haben (oder gerade bauen), was sind die Dinge, die Ihr Team am meisten beunruhigen? Formulieren Sie diese als Risikoaussagen. Ich mag den Bedingungs-Konsequenz-Stil des SEI, aber es gibt noch andere. Beispiele:

• Das Datenmodell ist groß und komplex. Entwickler wissen möglicherweise nicht, welche Datenelemente in einer bestimmten Situation verwendet werden sollen.
• Das System verfügt über API-Verbindungsbeschränkungen, um die Zuverlässigkeit zu erhöhen. Entwickler könnten versehentlich das Verbindungslimit überschreiten.
• Plug-Ins werden in mehreren aufeinander folgenden Schritten verwendet. Entwickler erstellen möglicherweise keine Plug-Ins, die diese geordneten Schritte berücksichtigen.

Priorisieren Sie jetzt als Team die Risiken. Multi-Voting funktioniert sehr gut.

Reduzieren Sie die Risiken mit der höchsten Priorität und wiederholen Sie den Vorgang mit der Identifizierung, bis das Risiko eines Projektversagens (definiert durch die Erfolgsschwelle) innerhalb eines tolerierbaren Bereichs liegt. Im Allgemeinen bedeutet dies, dass Sie einige Risiken haben, denen das Team zustimmt, dass dies kein großes Problem darstellt. Denken Sie daran, dass Sie wahrscheinlich nicht alle Risiken minimieren möchten. Eine beispielhafte Strategie zur Reduzierung des letzten oben genannten Risikos könnte darin bestehen, ein Lernprogramm zu erstellen.

So wenig wie möglich, aber so viel wie nötig

Ich kann mich nicht erinnern, wo und wann ich das zum ersten Mal gehört habe, aber es ist eine Maxime bei vielen Anwendungen.

Je komplexer die Technologie oder die Anwendung ist, desto mehr Dokumentation wäre (offensichtlich) erforderlich, aber Sie möchten natürlich keine Zeit damit verschwenden, über Bord zu gehen.

JohnFx 'Flurtest' ist gesund. Aber vertraue dir selbst; Sie haben den Code entwickelt, und ausgerechnet Sie sollten ein Gespür für die Elemente haben, die besondere Aufmerksamkeit erfordern, und für die Elemente, die für alle offensichtlich sind. Denken Sie an die Probleme, die Sie bei der Entwicklung des Codes hatten, und Sie werden wahrscheinlich eine Vorstellung davon haben, was ein anderer Entwickler sehen wird, wenn er Ihren Code betrachtet.

Vergessen Sie jeglichen Zusammenhang zwischen Aufwand beim Codieren und Aufwand beim Dokumentieren.

Ich glaube, Sie können das nicht in exakte Regeln setzen. Der Grund für die Dokumentation besteht darin, das Wissen, das nicht einfach aus dem Rohcode gewonnen wird, in einer Form bereitzustellen, damit andere den Rohcode verstehen und möglicherweise sogar warten können.

Daher können Sie nur feststellen, ob Sie genug dokumentiert haben, indem Sie die Zielgruppe fragen, ob es gut genug ist. Ich glaube, der "Peer Review" -Prozess ist sehr gut darin, dies im Vorfeld zu tun. Beachten Sie, wie viel Erklärungen erforderlich sind, damit Ihre Kollegen verstehen, wovon Sie sprechen, und arbeiten Sie daran, dies zu minimieren.

Wenn Sie dies noch nie getan haben, können Sie den Arbeitsaufwand nicht abschätzen, aber nach einigen Iterationen erhalten Sie eine bessere Vorstellung davon, wie viel benötigt wird.