Methodik zur Dokumentation der vorhandenen Codebasis

Ich arbeite als Teil eines Teams an einer vorhandenen Anwendung, für die es keine Inline-Dokumentation und keine technische Dokumentation gibt. Da ich an verschiedenen Fehlerberichten für die Anwendung gearbeitet habe, habe ich eine Art Breadcrumb-Trail für mich geschrieben - Fehlernummern an verschiedenen Stellen, damit der nächste Entwickler anhand dieser Fehlernummer sehen kann, was los ist.

Meine Frage lautet also:

Was ist die effizienteste Methode zur Dokumentation dieses Codes? Sollte ich dokumentieren, während ich den Bereich berühre (die Virenmethode, wenn Sie so wollen), oder sollte ich aus jedem Abschnitt für sich dokumentieren und keinen Pfaden folgen, die in andere Bereiche der Anwendung verzweigen? Sollte ich Inline-Kommentare einfügen, wo vorher keine existierten (mit der Befürchtung, dass ich falsch identifiziere, was der Code tut)?

Mit welcher Methode können Sie eine ziemlich große Anwendung, für die keine Inline-Dokumentation vorhanden ist, oder Inline-Verweise auf externe Dokumentation genau und schnell dokumentieren?

Dokumentation älterer Codebasen

Ich würde wärmstens empfehlen, die Scout-Regel mit älteren Codebasen zu befolgen. Der Versuch, ein Legacy-Projekt unabhängig von der Bearbeitung zu dokumentieren, wird niemals stattfinden.

In-Code-Dokumentation

Das Wichtigste ist, die Dokumentationsfunktionen in der von Ihnen gewählten Entwicklungsumgebung zu verwenden, dh pydoc für Python, Javadoc in Java oder XML-Kommentare in C #. Dies erleichtert das Schreiben der Dokumentation gleichzeitig mit dem Schreiben des Codes.

Wenn Sie darauf vertrauen, dass Sie später zurückkehren und die Dinge dokumentieren, kommen Sie vielleicht nicht daran vorbei, aber wenn Sie dies tun, während Sie den Code schreiben, ist das, was dokumentiert werden muss, in Ihrem Kopf frisch. C # bietet sogar die Möglichkeit, eine Kompilierungswarnung auszugeben, wenn die XML-Dokumentation unvollständig oder mit dem tatsächlichen Code nicht konsistent ist.

Tests als Dokumentation

Ein weiterer wichtiger Aspekt ist eine gute Integration und Unit-Tests.

Oft konzentriert sich die Dokumentation darauf, was Klassen und Methoden für sich tun, und überspringt, wie sie zur Lösung Ihres Problems zusammen verwendet werden. Tests stellen diese häufig in einen Zusammenhang, indem sie zeigen, wie sie miteinander interagieren.

In ähnlicher Weise weisen Unit-Tests häufig explizit auf externe Abhängigkeiten hin, durch die die Dinge nachgebildet werden müssen.

Ich finde auch, dass ich mit testgetriebener Entwicklung Software schreibe, die einfacher zu bedienen ist, weil ich sie von Anfang an benutze. Mit einem guten Test-Framework ist es oft dasselbe, Code einfacher zu testen und benutzerfreundlich zu machen.

Dokumentation auf höherer Ebene

Schließlich müssen Sie noch die Systemebene und die Architekturdokumentation berücksichtigen. Viele befürworten das Schreiben einer solchen Dokumentation in einem Wiki oder die Verwendung von Word oder einem anderen Textverarbeitungsprogramm, aber für mich ist der beste Ort für eine solche Dokumentation neben dem Code auch ein Nur-Text-Format, das für das Versionskontrollsystem geeignet ist.

Genau wie bei der In-Code-Dokumentation ist es wahrscheinlicher, dass Sie Ihre Dokumentation auf höherer Ebene in Ihrem Code-Repository auf dem neuesten Stand halten. Sie haben auch den Vorteil, dass Sie beim Herausziehen der Version XY des Codes auch die Version XY der Dokumentation erhalten. Wenn Sie ein VCS-freundliches Format verwenden, bedeutet dies außerdem, dass es einfach ist, genau wie Ihr Code zu verzweigen, zu unterscheiden und zusammenzuführen.

Ich mag erstens , da es einfach ist, sowohl HTML-Seiten als auch PDF-Dokumente daraus zu erstellen, und viel freundlicher als LaTeX ist , aber auch LaTeX-mathematische Ausdrücke enthalten kann, wenn Sie sie benötigen.

Schwierige Frage. Grundsätzlich würde ich die "Refactoring" -Methode verwenden, die ich als "Wenn Sie den Code berühren, dokumentieren" wiedergeben würde.

Aber um genau zu sein; Wenn Probleme auftauchen und Sie sich mit dem Code vertraut machen müssen, um die auftretenden Fehler zu beheben, sollten Sie diese Vertrautheit verwenden, um insbesondere Kommentare zu diesem Code zu verfassen. Im Wesentlichen hat Sie die Motivation, den Fehler zu diesem Zeitpunkt zu beheben, dazu gezwungen, sich mit dem Code vertraut zu machen, um ihn dokumentieren zu können. Und aus diesem Grund würde ich es ablehnen, nicht verwandten Zweigen zu folgen ODER nicht verwandte Funktionen zu dokumentieren, denn wenn Sie zu diesem Zeitpunkt keinen aktiven Test des Codes durchführen (um Ihre Fehlerbehebung zu überprüfen), ist es schwierig, vollständig zu sein sicher, dass Sie genau verstehen, was der Code tut und warum. (Ich gehe nicht auf das Problem ein, dass es auch schwierig sein kann, genau herauszufinden, was und warum der Code das tut, was er tut, selbst wenn Sie eine Fehlerbehebung testen.)

Dieser Ansatz sollte dazu tendieren, die Genauigkeit zu maximieren, wobei die Gesamtgeschwindigkeit geopfert wird, ohne jedoch die Notwendigkeit zu beeinträchtigen, den Code gleichzeitig zu stark zu pflegen. Wenn Ihre Bugfixing-Aufgaben gering sind, können Sie natürlich in "unbekanntes Gebiet" vordringen und dort mit der Dokumentation beginnen, aber wenn Sie (wie die meisten von uns) nicht genug Zeit am Tag finden, um den Code zu reparieren und zu dokumentieren, können Sie dies tun ist ein guter Kompromiss.

Eines ist auch zu bemerken; Sie sollten eine gute externe Dokumentation haben. Sie sagen, dass Ihr Code keine Verweise auf externe Dokumentation enthält. Ich hoffe für Sie, dass es eine solche externe Dokumentation gibt. Wenn nicht, würde ich das Schreiben dieser externen Dokumentation zu Ihrer obersten Priorität machen. Etwas auf der Ebene einer funktionalen Spezifikation ist meiner Meinung nach für alle großen Softwareprojekte absolut entscheidend. Der Grund dafür ist, dass Funktionsspezifikationen oder eine Dokumentation auf hoher Ebene dieses Formulars dazu beitragen können, "Feature Creep" oder "Feature Drift" in jeder Software zu verhindern. Insbesondere Feature-Drift kann die Dokumentation zerstören, da sie veraltet sein kann. (Ich definiere Feature Creep als das fortschreitende (und ärgerliche) Hinzufügen von Features zu einer Software; Feature DriftAuf der anderen Seite ändert sich die Menge der von der Software ausgeführten Aktionen mit der Zeit. Feature Creep ist ADDITIVE, dh es wird in der Regel der Funktionsumfang der Software erweitert. Die Merkmalsdrift ist dagegen Nullsumme; Einer nach dem anderen wird eine Edge-Funktionalität definiert, um etwas anderes zu tun, bis die Software etwas völlig anderes tut als ursprünglich beabsichtigt. Merkmalsdrift ist selten, aber TÖDLICH zur Dokumentation.)

Eine Anwendung, die ich im Laufe von zwei Jahren mitentwickelt habe, hatte einen gravierenden Mangel an Dokumentation. Irgendwann wurde klar, dass wir die Anwendung an einen anderen Entwickler weitergeben würden, der sie von diesem Zeitpunkt an warten würde, sodass wir den Code dokumentieren mussten.

Um den gigantischen Umfang des Dokumentationsprozesses zu bewältigen, würde ich versuchen, den gesamten Code an einem bestimmten Tag in einem bestimmten Feature oder Teil der App zu dokumentieren. Ich hatte kein bestimmtes Muster, bestand aber darauf, jeden Tag einiges zu tun und ein Gefühl der Vollendung zu bekommen, indem ich täglich eine ganze Datei oder einen Abschnitt der App dokumentierte.

Es dauerte Monate, um die gesamte Bewerbung zu dokumentieren, aber bis zu einer halben Stunde (max.) Am Tag hat es sich nie wirklich in den Projektplan eingemischt und viel Langeweile vermieden, die mit der Dokumentation einhergeht.

Wir haben die XML-Dokumentation in C # verwendet und es wurden genügend Funktionen und Strukturen bereitgestellt, um die Dokumentation zu vereinfachen. Auch wenn Sie keine C # -App dokumentieren, war das Muster, zuerst eine kurze Zusammenfassung gefolgt von Anmerkungen zu haben, sehr nützlich.

Ich würde dokumentieren, wie ich Code hinzufügte / änderte. Ansonsten würde ich auch öffentliche APIs oder Schnittstellen zwischen Modulen dokumentieren. Wenn Sie den gesamten Code dokumentieren, wird der ROI für die aufgewendete Zeit möglicherweise nicht angezeigt. Es kann nützlich sein, so etwas wie ein Wiki zu verwenden, um externe Dokumentation während der Entwicklung zu organisieren. Das nützlichste Dokument, auf das ich beim Start meines letzten Projekts verwiesen habe, war das Architekturdokument. Es enthielt Informationen zu den verwendeten Technologien und bot einen umfassenden Überblick über die Ebenen der Anwendung.

Ich würde Doxygen-Kommentare verwenden. Doxygen hat mehr Ausgabeformate als die meisten anderen freien Formate und ist einfach zu erlernen.

Sie könnten sogar in Betracht ziehen, einen Auftragnehmer dafür zu beauftragen, wie es einige von uns für ihren Lebensunterhalt tun. Bei dieser Auswahl müssen Sie sich jedoch noch verpflichten, die Dokumente zu überprüfen.

Eine andere übliche Technik besteht darin, den neuen Entwickler der Dokumentation des Codes zuzuweisen. Lassen Sie dann jede neue Person durchgehen, um sich auf den neuesten Stand zu bringen. Beachten Sie, dass einige Entwickler dies als Wurzelkanal betrachten - nur in den direkten Fällen notwendig, LOL.

Entwickeln Sie einen Standard, bevor Sie mit der Dokumentation beginnen. Dies kann so einfach sein, dass Sie sicherstellen, dass Sie ein paar Zeilen über einer Funktions- oder Klassenüberschrift in etwas Offizielleres und Ausführlicheres (wie Javadoc) schreiben. Bevor jemand Code einchecken kann, muss seine Dokumentation diesem Standard entsprechen.

Was ich als gut befunden habe, ist, gut geschriebene Kommentare vor dem Funktionsheader zu Funktionen hinzuzufügen, die ich erstellt habe und die zuvor nicht dokumentiert waren, und Inline-Kommentare zu allem hinzuzufügen, was ich hinzugefügt habe. Sie möchten vermeiden, Code zu dokumentieren, den Sie nicht berührt haben. Schlechte Kommentare sind schlimmer als gar keine. Wenn Sie dies schnell dokumentieren, werden Sie wahrscheinlich schlechte Kommentare verfassen.