Wie mache ich eine Dokumentation für Code und warum ist Software (oft) schlecht dokumentiert?

Es gibt einige gute Beispiele für gut dokumentierten Code, wie Java API. Aber eine Menge Code in öffentlichen Projekten wie Git und internen Projekten von Unternehmen ist schlecht dokumentiert und nicht sehr einsteigerfreundlich.

In all meinen Softwareentwicklungsphasen musste ich mich mit schlecht dokumentiertem Code auseinandersetzen. Ich habe die folgenden Dinge bemerkt -

1. Wenig oder keine Kommentare im Code.
2. Methoden- und Variablennamen sind nicht selbsterklärend.
3. Es gibt wenig oder keine Dokumentation darüber, wie der Code in das System oder die Geschäftsprozesse passt.
4. Schlechte Entwickler einstellen oder die Guten nicht betreuen. Sie können keinen einfachen und sauberen Code schreiben. Daher ist es für jedermann, einschließlich des Entwicklers, schwierig oder unmöglich, den Code zu dokumentieren.

Infolgedessen musste ich viel Code durchgehen und mit vielen Leuten sprechen, um Dinge zu lernen. Ich fühle, das verschwendet jedermanns Zeit. Es werden auch KT- / Wissenstransfersitzungen für Neulinge in einem Projekt benötigt.

Ich habe erfahren, dass der Dokumentation aus folgenden Gründen nicht die gebührende Aufmerksamkeit geschenkt wird:

1. Faulheit.
2. Entwickler machen nur Code.
3. Berufssicherheit. (Wenn niemand Ihren Code leicht verstehen kann, sind Sie möglicherweise nicht leicht zu ersetzen.)
4. Schwierige Fristen lassen wenig Zeit zum Dokumentieren.

Daher frage ich mich, ob es eine Möglichkeit gibt, gute Dokumentationspraktiken in einem Unternehmen oder Projekt zu fördern und durchzusetzen. Welche Strategien sind anzuwenden, um eine anständige Dokumentation für die Systeme und den Code eines Projekts zu erstellen, unabhängig von seiner Komplexität? Gibt es gute Beispiele dafür, wann minimale oder keine Dokumentation benötigt wird?

Meiner Meinung nach sollten wir eine Überprüfung der Dokumentation durchführen, nachdem ein Projekt abgeschlossen wurde. Wenn es nicht einfach, prägnant, anschaulich und benutzerfreundlich ist, ist der Entwickler oder der technische Dokumentationsingenieur dafür verantwortlich und muss es beheben. Ich erwarte auch nicht, dass die Leute Unmengen an Dokumentationen erstellen, und hoffe nicht, dass es benutzerfreundlich ist wie die Head-First-Bücher, aber ich erwarte, dass es keine stundenlangen Analysen und verschwenderischen KT-Sitzungen mehr braucht.

Gibt es eine Möglichkeit, diesen Wahnsinn zu beenden oder zu lindern? "Dokumentenorientierte Entwicklung" vielleicht?

Wie dokumentiere ich Code?

Sie haben bereits einen Hinweis: Sehen Sie sich an, wie die Java-API dokumentiert ist.

Im Allgemeinen gibt es keine eindeutigen Regeln, die für jedes Projekt gelten. Wenn ich an geschäftskritischen Großprojekten arbeite, hat die Dokumentation nichts mit der zu tun, die ich für eine kleine Open Source-Bibliothek schreiben würde, was wiederum nichts mit der Dokumentation meines mittelgroßen persönlichen Projekts zu tun hat .

Warum sind viele Open Source-Projekte nicht gut dokumentiert?

Weil die meisten Open-Source-Projekte von Leuten gemacht werden, die zu diesen Projekten beitragen, weil es Spaß macht. Die meisten Programmierer und Entwickler sind der Meinung, dass das Schreiben von Dokumentationen nicht Spaß genug macht , um kostenlos zu sein.

Warum sind viele Closed-Source-Projekte nicht gut dokumentiert?

Weil es eine Menge Geld kostet, (1) gute Dokumentation zu schreiben und (2) zu pflegen.

1. Die unmittelbaren Kosten (Kosten für das Verfassen der Dokumentation) sind für die Beteiligten klar erkennbar: Wenn Ihr Team die nächsten zwei Monate für die Dokumentation des Projekts benötigt, müssen zwei zusätzliche Monatsgehälter bezahlt werden.

2. Die langfristigen Kosten (Kosten für die Wartung der Dokumentation) werden auch für die Manager ziemlich leicht erkennbar und sind häufig das erste Ziel, wenn sie die Kosten senken oder die Verzögerungen verkürzen müssen. Dies führt zu einem zusätzlichen Problem veralteter Dokumentation, die schnell unbrauchbar und in der Aktualisierung extrem teuer wird.

3. Die langfristigen Einsparungen (Einsparungen, die dadurch entstehen, dass Sie nicht ein paar Tage mit dem Erforschen des Legacy-Codes verschwenden müssen, um eine grundlegende Sache zu verstehen, die vor Jahren hätte dokumentiert werden müssen) sind andererseits schwer zu messen, was das Gefühl einiger Manager bestätigt Das Verfassen und Verwalten von Dokumentationen ist Zeitverschwendung.

Was ich oft beobachte ist, dass:

1. Zu Beginn ist das Team bereit, viel zu dokumentieren.

2. Im Laufe der Zeit erschweren Termindruck und mangelndes Interesse die Pflege der Dokumentation immer mehr.

3. Einige Monate später kann eine neue Person, die sich dem Projekt anschließt, die Dokumentation praktisch nicht verwenden, da sie überhaupt nicht dem tatsächlichen System entspricht.

4. Das Management macht die Entwickler dafür verantwortlich, dass sie die Dokumentation nicht gepflegt haben. Entwickler bitten, einige Wochen damit zu verbringen, es zu aktualisieren.

   • Wenn das Management dafür einige Wochen einräumt, wiederholt sich der Zyklus.

   • Wenn das Management aufgrund früherer Erfahrungen ablehnt, erhöht dies nur die schlechten Erfahrungen, da das Produkt nicht dokumentiert ist, aber einige Monate damit verbracht wurden, es zu schreiben und zu warten.

Die Dokumentation sollte ein kontinuierlicher Prozess sein, genau wie das Testen. Verbringen Sie eine Woche damit, ein paar Tausend LOCs zu programmieren, und es ist sehr, sehr schmerzhaft, wieder mit Tests und Dokumentationen zu beginnen.

Wie kann man das Team ermutigen, Unterlagen zu schreiben?

Ähnlich wie bei den Methoden, mit denen Menschen dazu ermutigt werden, sauberen Code zu schreiben, regelmäßig umzugestalten, Entwurfsmuster zu verwenden oder genügend Komponententests hinzuzufügen.

• Mit gutem Beispiel vorangehen. Wenn Sie eine gute Dokumentation schreiben, tun dies möglicherweise auch Ihre Paare.

• Führen Sie systematische Codeüberprüfungen durch, einschließlich formaler Codeüberprüfungen, die auf die Einsichtnahme in die Dokumentation abzielen.

• Wenn einige Mitglieder des Teams einer guten Dokumentation (oder überhaupt einer Dokumentation) besonders abgeneigt sind, besprechen Sie das Thema unter vier Augen mit ihnen, um zu verstehen, welche Hindernisse sie daran hindern, eine bessere Dokumentation zu verfassen. Wenn sie den Mangel an Zeit verantwortlich machen, sehen Sie die Quelle der Probleme.

• Machen Sie das Vorhandensein oder den Mangel an Dokumentation für ein paar Wochen oder Monate messbar, aber konzentrieren Sie sich nicht darauf. Sie können zum Beispiel die Anzahl der Kommentarzeilen pro LOC messen, machen dies jedoch nicht zu einer dauerhaften Maßnahme. Andernfalls schreiben Entwickler lange, aber bedeutungslose Kommentare, um die niedrigen Punktzahlen zu beseitigen.

• Verwenden Sie Gamification. Dies kommt zusammen mit dem vorherigen Punkt.

• Verwenden Sie eine positive / negative Verstärkung .

• (Siehe den Kommentar von SJuan76 ) Behandle das Fehlen von Kommentaren als Fehler. In Visual Studio können Sie beispielsweise eine Option zum Generieren von XML-Dokumentation aktivieren. Wenn Sie außerdem überprüfen, ob alle Warnungen als Fehler behandelt werden, wird die Kompilierung angehalten, wenn ein Kommentar am Anfang einer Klasse oder Methode fehlt.

  In Bezug auf die drei vorhergehenden Punkte sollte dieser Punkt mit Vorsicht verwendet werden. Ich habe es eine Weile mit einem besonders starken Team von Programmieranfängern verwendet und es endete mit StyleCop-kompatiblen Kommentaren wie diesen:

    /// <summary>
    /// Gets or sets the PrimaryHandling.
    /// </summary>
    public Workflow PrimaryHandling { get; set; }

die waren, hm ..., nicht besonders hilfreich.

Denken Sie daran: Nichts Automatisiertes kann Ihnen helfen, schlechte Kommentare zu finden, wenn Programmierer mit Ihnen schrauben wollen . Nur Codeüberprüfungen und andere menschliche Aufgaben werden helfen.

Gibt es gute Beispiele dafür, wann minimale oder keine Dokumentation benötigt wird?

Eine Dokumentation zur Erläuterung der Architektur und des Designs ist nicht erforderlich:

• Für einen Prototyp

• Für ein persönliches Projekt, das in ein paar Stunden geschrieben wurde, um eine Aufgabe zu erledigen, während Sie ziemlich sicher sind, dass dieses Projekt nicht länger aufrechterhalten wird,

• Bei jedem Projekt, bei dem aufgrund der geringen Größe und des besonders sauberen Codes offensichtlich ist, dass Sie mehr Zeit mit dem Verfassen von Dokumentationen verbringen, als bei allen zukünftigen Betreuern, die sich mit dem Code befassen.

In-Code-Dokumentation (Code-Kommentare) wird nach Ansicht einiger Entwickler nicht benötigt, wenn der Code selbstdokumentierend ist. Für sie ist das Vorhandensein von Kommentaren, außer in den seltenen Fällen, kein gutes Zeichen, sondern ein Zeichen dafür, dass der Code nicht klar genug umgestaltet wurde, ohne dass Kommentare erforderlich waren.

Ich bin der Meinung, dass wir eine Überprüfung der Dokumentation durchführen sollten, nachdem ein Projekt geliefert wurde.

Wenn Ihr Projekt mindestens einmal pro Woche geliefert wird, ist es der richtige Weg. Wenn Ihr Projekt nicht flexibel ist und alle sechs Monate geliefert wird, sollten Sie regelmäßigere Überprüfungen durchführen.

Ich denke, Sie sollten zwischen Kommentaren und Dokumentationen unterscheiden. Während Kommentare beschreibend sind, mangelt es ihnen an Konsistenz. Sie sind über den gesamten Code verteilt. Kommentare sollten niemals Code kompensieren, der nicht selbsterklärend genug ist, sondern andere Programmierer auf knifflige Teile hinweisen.

Ob Code dokumentiert werden soll, hängt vom Umfang des Projekts ab. Sicherlich gibt es Menschen, die glauben, dass alles dokumentiert werden sollte, und es scheint einfach, diesen Gedanken zu rechtfertigen, denn wer würde es wagen, sich der Dokumentation von Wissen zu widersetzen? Glücklicherweise ist Softwareentwicklung keine Wissenschaft und die Welt bricht nicht zusammen, wenn die Details hinter Ihrem kleinen Programm undeutlich werden. Was nun eine professionelle Software betrifft, die von vielen Entwicklern verwendet werden kann, sollten Sie Ihren Code natürlich dokumentieren. Aber wenn Sie in der Lage sind, auf dieser Ebene zu codieren, dann wissen Sie das offensichtlich.

tl; dr

Wenn Sie darum bitten, dass jedes Projekt gut dokumentiert ist, dann fragen Sie zu viel.