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

In all meinen Softwareentwicklungsaufenthalten 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 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 durchmachen Code und sprechen Sie mit vielen Menschen, um Dinge zu lernen. Ich glaube, dies verschwendet die Zeit aller. 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. Jobsicherheit. (Wenn niemand Ihren Code leicht verstehen kann, sind Sie möglicherweise nicht leicht austauschbar.)
  4. Schwierige Fristen lassen wenig Zeit zum Dokumentieren.

Ich frage mich also, ob es eine Möglichkeit gibt, gute Dokumentationspraktiken in einem Unternehmen oder Projekt zu fördern und durchzusetzen. Welche Strategien gibt es? Gibt es gute Beispiele dafür, wann nur minimale oder keine Dokumentation erforderlich ist?

Meiner Meinung nach sollten wir dies tun, um eine anständige Dokumentation für die Systeme und den Code eines Projekts zu erstellen, unabhängig von dessen Komplexität Eine Überprüfung der Dokumentation nach Lieferung eines Projekts. Wenn es nicht einfach, präzise, illustrativ und benutzerfreundlich ist, trägt der Entwickler oder technische Dokumentationsingenieur die Verantwortung dafür und muss es reparieren. Ich erwarte auch nicht, dass die Leute Unmengen von Dokumentationen erstellen. Ich hoffe nicht, dass es benutzerfreundlich sein wird wie die Head-First-Bücher, aber ich erwarte, dass es die Notwendigkeit dafür beseitigt Stunden der Analyse und verschwenderische KT-Sitzungen.

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

Kommentare

  • Es gibt einen weiteren Grund, warum es häufig keine ordnungsgemäße Dokumentation gibt: Es ist sehr schwierig, eine gute Dokumentation zu schreiben, die nicht ‚ paraphrasiert den Code nicht nur auf Englisch, sondern beschreibt warum der Code so entworfen / geschrieben ist. Die Notwendigkeit dieser Informationen wird erst Monate nach dem Aufschreiben deutlich.
  • Ein weiterer schwerwiegender Grund: Viele Entwickler haben Englisch als Zweitsprache und / oder schreiben Englisch schlecht . Sie könnten sie nur zwingen, einen Einzeiler für eine Methode zu schreiben, aber wenn Sie eine gute Dokumentation wünschen, sollten Sie besser darauf vorbereitet sein, dafür zu bezahlen, und Spezialisten damit beauftragen.

Antwort

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 erstellt werden, die zu diesen Projekten beitragen, weil es Spaß macht. Die meisten Programmierer und Entwickler ziehen dies in Betracht dass das Schreiben von Dokumentation nicht genug Spaß macht , um kostenlos durchgeführt zu werden.

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

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

  1. Die sofortige Die Kosten (Kosten für das Schreiben der Dokumentation) sind für die Stakeholder deutlich sichtbar: 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 lo Die Laufzeitkosten (Kosten für die Pflege der Dokumentation) werden auch für die Manager recht einfach spürbar 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, das schnell unbrauchbar wird und extrem teuer zu aktualisieren ist.

  3. Die langfristigen Einsparungen (Einsparungen, da Sie nicht ein paar Tage damit verbringen müssen, das zu erkunden Legacy-Code, nur um eine grundlegende Sache zu verstehen, die vor Jahren hätte dokumentiert werden müssen, ist andererseits schwer zu messen, was das Gefühl einiger Manager bestätigt, dass das Schreiben und Verwalten von Dokumentation Zeitverschwendung ist.

Was ich oft beobachte, ist Folgendes:

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

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

  3. Einige Monate Später kann eine neue Person, die dem Projekt praktisch beitritt, die Dokumentation nicht verwenden, da sie überhaupt nicht dem tatsächlichen System entspricht.

  4. Das Management bemerkt dies und gibt den Entwicklern die Schuld für die Nichtpflege der Dokumentation; Entwickler bitten darum, einige Wochen mit der Aktualisierung zu verbringen.

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

    • 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.

    / ol>

    Die Dokumentation sollte wie das Testen ein kontinuierlicher Prozess sein. 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 Sie das Team zum Schreiben ermutigen Dokumentation?

    Ähnlich wie 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 Ü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 verantwortlich machen, sehen Sie die Ursache der Probleme.

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

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

    • Verwenden Sie eine positive / negative Verstärkung .

    • (Siehe den 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 auch überprüfen, ob alle Warnungen als Fehler behandelt werden, wird die Kompilierung durch das Fehlen eines Kommentars am Anfang einer Klasse oder einer Methode angehalten.

      Für die drei vorherigen Punkte sollte dieser verwendet werden mit Vorsicht. Ich habe es eine Weile mit einem besonders harten 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, hm …, nicht besonders hilfreich waren.

    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 menschliche Aufgaben helfen.

    Gibt es gute Beispiele dafür, wann nur minimale oder keine Dokumentation erforderlich ist?

    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 erfüllen, obwohl Sie sich ziemlich sicher sind, dass dieses Projekt nicht mehr gepflegt wird,

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

    In-Code-Dokumentation (Codekommentare) 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 genug überarbeitet wurde, um klar zu sein, 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 geliefert wird einmal pro Woche ist es 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.

    Kommentare

    • An ‚ wie man ‚ ermutigt, möchte ich hinzufügen, dass viele IDEs die Benachrichtigung über fehlende Dokumentation als Warnungen zulassen. Alternativ kann möglicherweise eine statische Analyse der Dokumentation am OSB durchgeführt werden (das allein würde natürlich nicht ausreichen).
    • @ SJuan76: In der Tat. Visual Studio kann das Fehlen von Kommentaren sogar als Fehler beim Kompilieren behandeln. Ich habe meine Antwort bearbeitet, um einen Hinweis dazu hinzuzufügen.
    • @ArseniMourzenko – Ich habe gelesen, dass wir einige Dokumentationen in Agile fördern können, indem wir Geschichten zur Dokumentation hinzufügen. Diese sollten jedoch nicht die anderen Storys blockieren, d. H. Die Definition anderer Storys von „erledigt“, und dürfen nicht die Vervollständigung von Dokumentationsgeschichten beinhalten. Wie klingt das?
    • @ArseniMourzenko – Ich ‚ möchte Ihrer Antwort zwei weitere Punkte hinzufügen. (1) Fügen Sie in Jira usw. ständig eine Aufgabe zur Dokumentation hinzu. (2) Lassen Sie Dokumente, die von 2 weiteren Personen & überprüft wurden, dies ebenfalls als Aufgabe betrachten. Auf diese Weise werden die Benutzer daran erinnert, dass & das Schreiben von Dokumenten mit geringer Qualität (aufgrund von Überprüfungen) vermieden wird. Wenn Sie ‚ keine Prioritäten setzen & überprüfen, wird es schlecht. Ich weiß, dass Amazon viele Dokumente & Dokumentprüfungen durchführt, möglicherweise etwas zu viel.

Antwort

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 zu widersetzen Wissen dokumentieren? Glücklicherweise ist Softwareentwicklung keine Wissenschaft, und die Welt bricht nicht zusammen, wenn die Details hinter Ihrem kleinen Programm unklar werden. Nun zu einer professionellen Software, die von vielen Entwicklern verwendet wird, sollten Sie natürlich Ihren Code dokumentieren. Aber wenn Sie in der Lage sind Wenn Sie auf dieser Ebene codieren möchten, wissen Sie das offensichtlich.

tl; dr

Wenn Sie „verlangen, dass jedes Projekt gut dokumentiert wird, dann fragen Sie zu viel.“

Kommentare

  • Fortunately software development is not science Bitte erzählen Sie mir mehr darüber, warum Sie das glauben.
  • @Borat – Softwareentwicklung ist eine technische Disziplin, die impliziert, dass sie die von der Wissenschaft bereitgestellten Tools verwendet.
  • Ich bitte nicht, dass alles dokumentiert wird. Es sollte so sein gerade genug, um einen allgemeinen Überblick über die Funktionsweise eines Systems und Codes zu geben. ZB sagen Sie mir bitte, wie ich mein Fernsehgerät verwenden soll. ‚ ist es egal, ob es LCD, CRT, verwendet. Vakuumröhren oder Festkörpergeräte, um die Arbeit zu erledigen . Wenn ein Reparaturmann diese Informationen wünscht, erstellen Sie eine separate Dokumentation für ihn.
  • Wenn Sie eine allgemeine Übersicht wünschen, reichen die Bezeichnernamen aus. Genau wie die Taste auf Ihrem Fernseher möglicherweise ein “ auf “ -Label hat. Sie fragen also nach Details auf niedriger Ebene.
  • @LeopoldAsperger: Ich denke, Borat spricht von der Dokumentation von Architektur und Design, nicht von Methoden in Klassen.

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.