it-swarm.com.de

Wie wird Code dokumentiert und warum ist Software (oft) schlecht dokumentiert?

Es gibt einige gute Beispiele für gut dokumentierten Code, wie Java api.) Aber viel Code in öffentlichen Projekten wie Git und internen Projekten von Unternehmen ist schlecht dokumentiert und nicht sehr Neuling freundlich.

In all meinen Softwareentwicklungsaufenthalten musste ich mich mit schlecht dokumentiertem Code auseinandersetzen. Ich habe folgende Dinge bemerkt -

  1. Wenig oder keine Kommentare im Code.
  2. Methoden- und Variablennamen sind nicht selbstbeschreibend.
  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 niemanden, einschließlich des Entwicklers, schwierig oder unmöglich, den Code zu dokumentieren.

Infolgedessen musste ich viel Code durchgehen und mit vielen Menschen sprechen, um Dinge zu lernen. Ich habe das Gefühl, dass dies die Zeit aller verschwendet. Außerdem werden KT/Wissenstransfersitzungen für Projektneulinge benötigt.

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

  1. Faulheit.
  2. Entwickler machen nur Code.
  3. Berufssicherheit. (Wenn niemand Ihren Code leicht verstehen kann, sind Sie möglicherweise nicht leicht austauschbar.)
  4. Schwierige Fristen lassen wenig Zeit für die Dokumentation.

Ich frage mich also, ob es eine Möglichkeit gibt, gute Dokumentationspraktiken in einem Unternehmen oder Projekt zu fördern und durchzusetzen. Welche Strategien müssen verwendet werden, 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 nur minimale oder keine Dokumentation benötigt wird?

Meiner Meinung nach sollten wir nach der Lieferung eines Projekts eine Überprüfung der Dokumentation durchführen lassen. Wenn es nicht einfach, präzise, ​​illustrativ und benutzerfreundlich ist, trägt der Entwickler oder Techniker der technischen Dokumentation die Verantwortung dafür und muss es reparieren. Ich erwarte auch nicht, dass die Leute Unmengen von Dokumentationen erstellen, und hoffe nicht, dass sie benutzerfreundlich sind wie die Head-First-Bücher, aber ich erwarte, dass sie keine stundenlangen Analysen und verschwenderischen KT-Sitzungen erfordern.

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

26
Erran Morad

Wie dokumentiere ich Code?

Sie haben bereits einen Hinweis: Sehen Sie sich an, wie 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 Dokumentation nicht genug Spaß macht , um kostenlos durchgeführt zu werden.

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

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

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

  2. Die langfristigen Kosten (Kosten für die Wartung der Dokumentation) werden auch für die Manager ziemlich einfach spürbar und sind oft 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, das schnell unbrauchbar wird und dessen Aktualisierung extrem teuer ist.

  3. Die langfristigen Einsparungen (Einsparungen, die dadurch entstehen, dass Sie nicht ein paar Tage damit verbringen müssen, den Legacy-Code zu erkunden, 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 Schreiben und Verwalten von Dokumentationen ist Zeitverschwendung.

Was ich oft beobachte, ist Folgendes:

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

  2. Mit der Zeit erschweren Termindruck und mangelndes Interesse die Pflege der Dokumentation.

  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 stellt fest, dass das Entwickler die Entwickler beschuldigt, die Dokumentation nicht gepflegt zu haben. Entwickler bitten darum, einige Wochen damit zu verbringen, es zu aktualisieren.

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

    • Wenn sich das Management aufgrund früherer Erfahrungen weigert, erhöht dies nur die schlechte Erfahrung, da dem Produkt die Dokumentation fehlt, aber einige Monate damit verbracht wurden, es zu schreiben und zu warten.

Dokumentation sollte ein kontinuierlicher Prozess sein, genau wie das Testen. Verbringen Sie eine Woche damit, einfach ein paar Tausend LOC zu codieren, und es ist sehr, sehr schmerzhaft, zu Tests und Dokumentationen zurückzukehren.

Wie kann man das Team ermutigen, Dokumentation zu schreiben?

Ähnlich wie die Leute 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 formeller Codeüberprüfungen, die auf die Überprüfung der Dokumentation abzielen.

  • Wenn einige Mitglieder des Teams einer guten Dokumentation (oder überhaupt einer Dokumentation) besonders abgeneigt sind, besprechen Sie das Thema privat mit ihnen, um zu verstehen, welche Hindernisse sie daran hindern, eine bessere Dokumentation zu schreiben. Wenn sie den Zeitmangel beschuldigen, sehen Sie die Ursache der Probleme.

  • Machen Sie das Vorhandensein oder den Mangel an Dokumentation für einige Wochen oder Monate messbar, aber konzentrieren Sie sich nicht darauf. Sie können beispielsweise die Anzahl der Kommentarzeilen pro LOC messen, diese jedoch nicht dauerhaft festlegen. Andernfalls schreiben Entwickler lange, aber bedeutungslose Kommentare, um niedrige Punktzahlen zu vermeiden.

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

  • Verwenden Sie positiv/negativ Verstärkung .

  • (Siehe der Kommentar von SJuan76 ) Behandeln Sie 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 durch das Fehlen eines Kommentars am oberen Rand einer Klasse oder Methode angehalten.

    Die drei vorhergehenden Punkte sollten mit Vorsicht verwendet werden. Ich habe es eine Weile mit einem besonders harten Team von Anfängerprogrammierern verwendet, und es endete mit StyleCop-konformen 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 lokalisieren, wenn Programmierer mit Ihnen schrauben möchten . Nur Codeüberprüfungen und andere human Aufgaben werden helfen.

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

Eine Dokumentation zur Erläuterung der Architektur und des Designs wird nicht benötigt:

  • Für einen Prototyp

  • Für ein persönliches Projekt, das in wenigen Stunden geschrieben wurde, um eine Aufgabe zu erledigen, obwohl Sie sich ziemlich sicher sind, dass dieses Projekt nicht mehr gewartet wird,

  • Für jedes Projekt, bei dem es angesichts der geringen Größe und des besonders sauberen Codes offensichtlich ist, dass Sie mehr Zeit mit dem Schreiben von Dokumentationen verbringen als alle zukünftigen Betreuer, die den Code untersuchen.

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 so überarbeitet wurde, dass er klar ist, ohne dass Kommentare erforderlich sind.

Ich bin der Meinung, dass wir nach der Lieferung eines Projekts eine Überprüfung der Dokumentation durchführen sollten.

Wenn Ihr Projekt mindestens einmal pro Woche geliefert wird, ist dies der richtige Weg. Wenn Ihr Projekt nicht agil ist und im Abstand von sechs Monaten geliefert wird, führen Sie regelmäßigere Überprüfungen durch.

26

Ich denke, Sie sollten zwischen Kommentaren und Dokumentation 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 selbstbeschreibend genug ist, sondern andere Programmierer auf schwierige Teile hinweisen.

Ob Code dokumentiert werden soll, hängt vom Umfang des Projekts ab. Sicherlich gibt es Leute, die glauben, dass alles dokumentiert werden sollte, und es scheint leicht zu sein, 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 dunkel werden. In Bezug auf eine professionelle Software, die von vielen Entwicklern verwendet wird, sollten Sie natürlich Ihren Code dokumentieren. Aber wenn Sie in der Lage sind, auf dieser Ebene zu codieren, dann würden Sie das offensichtlich wissen.

tl; dr

Wenn Sie verlangen, dass jedes Projekt gut dokumentiert ist, fragen Sie zu viel.

3