Studien zu Produktivitätsgewinnen / -verlusten bei der Codedokumentation

Nach langem Suchen habe ich eine grundlegende Frage zu einer in der Welt der Softwareentwicklung bekannten Annahme nicht beantwortet:

WAS BEKANNT IST:

Die Durchsetzung einer strengen Richtlinie für eine angemessene Codedokumentation (sei es Doxygen-Tags, Javadoc oder einfach eine Fülle von Kommentaren) erhöht den Zeitaufwand für die Entwicklung von Code.

ABER:

Eine gründliche Dokumentation (oder sogar eine API) bringt Produktivitätssteigerungen (wie man annimmt) bei neuen und erfahrenen Entwicklern mit sich, wenn sie Funktionen hinzufügen oder später Fehler beheben.

DIE FRAGE:

Wird die zusätzliche Entwicklungszeit, die erforderlich ist, um eine solche Dokumentation zu gewährleisten, durch die Produktivitätsgewinne in der Zukunft (im streng wirtschaftlichen Sinne) ausgeglichen?

Ich suche nach Fallstudien oder Antworten, die objektive Beweise für die Schlussfolgerungen liefern können.

Danke im Voraus!

Der Artikel "Typografischer Stil ist mehr als kosmetisch" ist ziemlich alt, aber sehr interessant: http://portal.acm.org/citation.cfm?id=78611 .

Sein alt, nicht dazu gehören alle Phantasie Dinge , die in diesen Tagen möglich sein würde , aber es zeigt deutlich , dass Code - Dokumentation tut Angelegenheit.

Für diejenigen, die wie ich keinen Zugriff auf die digitale ACM-Bibliothek haben, haben sie zwei Gruppen von Programmierern erstellt und ihnen denselben Code zum Lernen gegeben. Die Gruppe A erhielt nur den Code mit den üblichen Kommentaren, Gruppe B erhielt eine hübsche gedruckte Auflistung mit Inhaltsverzeichnis, Querverweis und allen Feinheiten, die 1990 möglich waren.

Dann baten sie die beiden Gruppen, bestimmte Aufgaben am Code auszuführen (z. B. eine Funktion erweitern, einen Fehler finden, ...) und bewerteten sie hinsichtlich Geschwindigkeit und Qualität der Antworten.

Um die Gruppe auszugleichen, hatten sie die gleiche Anzahl von Experten und Junior-Programmierern.

Nun, es stellte sich heraus, dass Gruppe B (die mit der hübschen gedruckten Auflistung) in zahlreichen Tests cosistent besser abschnitt als Gruppe A. Und in bestimmten Fällen gelang es nur den Experten der Gruppe A, den Junior-Programmierer der Gruppe B zu übertreffen.

Der Artikel sagt mehr, aber das ist es, woran ich mich aus dem Gedächtnis erinnern kann (ich sollte den gedruckten Artikel noch irgendwo haben).

Zumindest für mich scheint es offensichtlich, dass lesbarer Code viel mehr wert ist als Dokumentation, die nur dazu dient, schlecht geschriebenen Code auszugleichen. Ich neige dazu, Kommentare im Code als Herausforderung zu betrachten, um zu sehen, ob ich den Kommentar entfernen kann, indem ich den Code neu schreibe und ihn selbsterklärender mache.

Ich kann das nicht mit harten Beweisen belegen, außer mit gesundem Menschenverstand.

Ich habe keine Studien zu zitieren, aber ich habe eine einfache Regel: Wenn ich zwei Wochen später zu meinem Code zurückkehre und nicht sofort herausfinden kann, was ich getan habe, braucht es entweder mehr Kommentare oder muss vereinfacht werden .

Sicherlich, wie Ihr Code funktioniert soll durch den Code selbst zu dokumentieren. Aber die Zeit, die Sie damit verbringen, Kommentare zu schreiben, die sorgfältig und prägnant erklären, warum Ihr Code so geschrieben ist, wie er sich auf lange Sicht mit ziemlicher Sicherheit auszahlt, selbst wenn Sie die einzige Person sind, die den Code verwaltet.

Die Lebensdauer einer Software wird hauptsächlich in der Wartungsphase verbracht. Alles, was dem Programmierer hilft, zu verstehen, was passiert, bringt mit ziemlicher Sicherheit finanzielle Renditen, da der Entwickler schneller auf den neuesten Stand gebracht werden kann.

Bei jeder API, die nicht trivial ist, ist die Dokumentation der API im Code nahezu nutzlos. Dies liegt daran, dass die Leistung der API davon abhängt, wie sie als Ganzes zusammenarbeitet (nicht davon, wie einzelne Methoden / Objekte funktionieren).

Hilfreicher als die eigentliche Dokumentation ist daher ein kochbuchähnliches Dokument, in dem die erwarteten Verwendungsmuster der API erläutert werden und Beispiele für die Lösung einiger offensichtlicher Situationen (bei denen die Mehrheit (nicht 100%) der API verwendet wird).

Die Entscheidung, ob eine bestimmte Methode ohne wahrscheinlich noch nicht erfundene Werkzeuge zu subjektiv ist , um eine schriftliche Dokumentation zu verlangen .

Best-Guess-Methoden wie "alle öffentlichen Methoden" oder alle Klassen in einem bestimmten Paket usw. können hilfreich sein, sind jedoch zu grob, um sie über bestimmte Anwendungsfälle hinaus zu empfehlen.

Mein Vorschlag: Bringen Sie Ihren Entwicklern bewährte Verfahren bei, wie Sie zu dokumentierende Methoden identifizieren (formelle oder informelle API, häufig verwendete, Stub-Methoden, komplex oder esoterisch) und lassen Sie sie sich selbst regieren.

(Eng verwandt: Können die Kodierungsstandards zu einheitlich sein? )

^{Entschuldigung, dass ich keine Studien zu zitieren habe, aber ich vermute, dass dies ein Problem ist, bei dem Versuche, es zu messen, das Ergebnis zu stark beeinflussen würden, um allgemeine Schlussfolgerungen zu ziehen.}

Ich denke, wir müssen in dieser Hinsicht "normalen" Code von öffentlichen APIs trennen . Für regulären Code bin ich der Meinung, dass die meisten anderen Antwortenden in diesem Code selbstdokumentierend sein und fast wie Prosa lesen sollten . Wenn mein Code nicht so ist, ist es normalerweise meine Schuld. Anstatt ihn zu dokumentieren, sollte er überarbeitet werden. Kleine Methoden, die jeweils nur eines tun, auf einer einzigen Abstraktionsebene arbeiten und einen korrekten und beschreibenden Namen haben , können einen großen Beitrag dazu leisten .

Das Problem mit Kommentaren ist, dass sie verrotten. Sobald Sie einen Kommentar hinzufügen, beginnt er ein Leben unabhängig von dem Code, den er begleitet. Wie groß ist die Chance, dass der nächste Entwickler, der den Code ändert, auch die zugehörigen Kommentare pflichtbewusst aktualisiert? Nach meiner Erfahrung nahe Null. Das Endergebnis nach einigen Änderungen ist, dass der Kommentar die Leute verwirrt oder irreführt, anstatt ihnen zu helfen.

Mögliche Ausnahmen sind leistungsoptimierter Code oder die Verwendung eines bestimmten Algorithmus . In diesem Fall ist es hilfreich, Kommentare hinzuzufügen, um zu beschreiben, warum der Code so aussieht, einen Verweis auf den Algorithmus usw.

Die wegweisende Arbeit zu diesem Thema ist Clean Code .

OTOH eine öffentliche API sollte auch in Javadoc wirklich gut dokumentiert sein. Da es von unzähligen völlig Fremden mit sehr unterschiedlichen Fähigkeiten und Annahmen verwendet werden kann, muss man alle Vorkehrungen treffen, um die Verwendung so einfach und eindeutig wie möglich zu gestalten. Das ist immer noch eine Frage des richtigen API-Designs, aber es gibt auch eine wichtige Rolle für die Dokumentation.

Das Problem ist, ob Sie Zeit sparen, indem Sie Ihren Code dokumentieren, und ob jeder nachfolgende Entwickler versuchen muss, herauszufinden, was er tut. Wenn Ihr Code die Codeüberprüfung durchläuft, ohne dass jemand Fragen dazu aufwirft, sind Sie wahrscheinlich in guter Verfassung. Es ist nicht allzu schwer, die Annahmen zu beschreiben, die Sie über Eingaben treffen. Angenommen, Ihre Methode nimmt ein ganzzahliges Objekt und gibt ein Zeichenfolgenobjekt zurück. Kann das int null sein? Gibt es einen Min / Max-Wert (neben integer.MinValue / MaxValue)? Kann es eine leere Zeichenfolge oder null zurückgeben? Wirft es irgendwelche Ausnahmen? Natürlich kann jeder diese durch Inspektion finden, aber wenn genügend andere Entwickler Ihren Code verwenden, lohnt es sich, alle paar Minuten zu sparen. Außerdem können Tester Tests erstellen, um Ihren Code zu bestätigen.

Dies ist sicherlich ein interessantes Thema, da es immer Argumente gab, ob Entwickler Zeit damit verbringen sollten, Dokumente zu erstellen oder zu pflegen oder nicht, aber Tatsache ist, dass Code gut geschrieben und sehr gut kommentiert sein sollte, auf diese Weise, wenn Entwickler den Code erneut besuchen, als er oder sie muss keine Zeit damit verbringen, darüber nachzudenken, wie Code geschrieben wurde und was er eigentlich tun sollte, wenn ein neues Teammitglied dem Team beitritt, als er auch die Funktionalität und Funktionsweise von Code verstehen kann, wie dies klar dokumentiert wurde.

Code sollte also sehr gut kommentiert sein und sollte selbstdokumentierter Code sein, für den keine externe Dokumentation erforderlich ist.

In meiner Karriere habe ich Code mit unterschiedlichen Dokumentations- und Qualitätsstufen gesehen (beachten Sie, dass Dokumentation und Qualität orthoganische Belange sind). Ich würde es vorziehen, die für die Dokumentation aufgewendete Zeit für die Verbesserung der Qualität zu verwenden. Für den einfachen Fall gibt es Tools wie GhostDoc, die eine Funktion anzeigen und Dokumentkommentare für Sie generieren können. Wenn GhostDoc einen aussagekräftigen Kommentar generieren kann, der besagt, was Ihre Funktion tut, haben Sie offensichtlich das Ziel erreicht, gut benannte Funktionen zu haben.

In vielen Fällen kann GhostDoc Ihnen nicht einmal sagen, was eine Funktion wirklich tut. Ihre Zeit wird besser damit verbracht, dieses Problem zu beheben und (möglicherweise) Ghostdoc zu verwenden, um Ihren Code automatisch zu generieren.

Weitere Informationen finden Sie unter Clean Code und PPP von Bob Martin.