Studien zu Produktivitätsgewinnen / -verlusten bei der Codedokumentation


11

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!


Wenn Sie nach Meinungen suchen, gehört diese auf programmers.se.
David Thornley

Ich bin nicht der Meinung, dass es hätte verschoben werden sollen. Zur Verdeutlichung suche ich STARK nach Studien, die durchgeführt wurden.
JT

Bearbeitet. Könnte ein Moderator dies bitte zurück zu Stack Overflow migrieren, wo diese Frage ein viel breiteres Publikum erfreut und somit seine Chancen erhöht.
JT

8
Ich denke nicht, dass dies eine geeignete Frage für SO ist, da es sich nicht um eine Codierungsfrage handelt, sondern um eine Frage zur Codierung. Ich denke tatsächlich, dass es eine perfekte Frage für Programmierer ist.
ChrisF

Antworten:


6

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


8

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.


Es ist wirtschaftlich sinnvoll, nur einige Javadoc durchlesen zu müssen, um eine Methode zu verwenden, anstatt die gesamte Methode durchlesen zu müssen
Heiko Rupp

2
@Heiko: Wenn Sie anhand des Funktionsnamens und der Parameternamen nicht herausfinden können, was eine Funktion tut, ist es Zeit, sie umzubenennen.
Sjoerd

4
Ich stimme dieser Antwort zu, aber manchmal müssen Sie Dokumentation hinzufügen für Dinge wie: Was sind die gültigen Rückgabewerte? Was sind die gültigen Eingabewerte? Wie passt dies zum Gesamtrahmen des Programms? Was sind die Anforderungen der Methode?
Dominique McDonnell

2
@Sjoerd: Das kann Ihnen einen umfassenden Überblick über die Funktionsweise der Methode geben, sagt Ihnen aber nicht alles. Zulässige Eingabewerte, was zurückgegeben werden kann, wie Fehler behandelt werden, welcher vorherige Status erwartet wird usw. können nur durch Auswahl geeigneter Methoden- und Parameternamen mitgeteilt werden.
Anon.

@Anon: Wenn ein vorheriger Status erforderlich ist, ist es Zeit für eine Neugestaltung. Fehler werden durch Auslösen von Ausnahmen behandelt (und Java listet die Typen auf - C ++ - und C # -Programmierer interessieren sich nicht für den Ausnahmetyp, sodass sie nicht dokumentiert werden müssen). Wichtig ist nur, ob Nullen akzeptiert oder zurückgegeben werden (was in C ++ durch Verwendung von Referenzen oder Zeigern signalisiert werden kann - Java ist in diesem Fall weniger klar und erfordert eine Dokumentation). Und selbst in diesem Fall können Namen hilfreich sein: Wenn FindFoo () beispielsweise null zurückgibt, wenn es nicht gefunden wird, löst GetFoo () eine Ausnahme aus, wenn es nicht gefunden wird.
Sjoerd

6

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.


3

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


+1 für Nutzungsmuster. Wenn ich nichts anderes hätte, mit dem ich arbeiten könnte, würden Codebeispiele ausreichen.
Robert Harvey

+1 für den hervorragenden Punkt, dass Codebeispiele vielleicht wichtiger sind als eine saubere API.
JT

@JT: Ich mag das Gefühl, aber ich würde es lieber umformulieren:Clean common usage scenarios are more important than a clean API
Martin York

1

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.


1

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.


1

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.


+1 für die Idee, die Codeüberprüfung als Mechanismus zu verwenden, um festzustellen, ob der Code ausführlich und sauber genug ist oder ob dies erforderlich ist. Auch ein ausgezeichneter Punkt darüber, wie eine saubere API Testern hilft, Komponententests zu schreiben
JT

0

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.


0

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.

Durch die Nutzung unserer Website bestätigen Sie, dass Sie unsere Cookie-Richtlinie und Datenschutzrichtlinie gelesen und verstanden haben.
Licensed under cc by-sa 3.0 with attribution required.