Im Laufe der Jahre habe ich an allen Arten von Projekten gearbeitet – groß, klein, chaotisch, überkonstruiert, „vorübergehend“, angeblich gut strukturiert und alles dazwischen. The documentation is always missing, outdated, or buried in some forgotten corner of Confluence guarded by a 2019 timestamp. Jedes Projekt um Dokumentation zu haben. Behauptungen Jedes Team Sie werden es aktualisiert halten. Versprechen Und jeder Entwickler sagt zuversichtlich: „Mach dir keine Sorgen, ich werde es später schreiben“, was, wie wir alle wissen, die Dokumentation entspricht, wenn man sagt: „Der Scheck ist in der Post.“ Nachdem ich beobachtet hatte, wie sich dieser Zyklus mehrmals wiederholt, als ich zugeben wollte, erkannte ich etwas einfaches, aber brutal wahr: 
 
 Dokumentation überlebt nur, wenn sie so nah wie möglich am Code lebt – denn Entwickler (einschließlich mich selbst) sind faule Kreaturen. Documentation only survives if it lives as close to the code as possible—because developers (myself included) are lazy creatures. Und daraus kam eine weitere Erkenntnis - das Hauptproblem mit veralteter Dokumentation ist die Tatsache, dass die meisten Teams sie nicht als Teil des Hauptentwicklungszyklus betrachten, sie für später lassen oder mit ein paar Pre-dev-Spezifikationen rechnen, die sie bereits irgendwo in Confluence hatten. Um sinnvolle Dokumentation zu schreiben, besprechen wir zuerst, welche Art von Dokumentation für eine Softwarekomponente vorhanden ist: Ways to Document Code (That Developers Might Actually Use) Wege zum Dokumentencode (Dass Entwickler tatsächlich verwenden könnten) Sobald Sie akzeptieren, dass die Dokumentation in der Nähe des Codes leben muss, ist die nächste Frage um es zu strukturieren. wie In der Praxis habe ich festgestellt, dass gute Dokumentation kein einziges Artefakt ist - es ist ein kleines Ökosystem von Schichten, die jeweils einem anderen Zweck und einem anderen Publikum dienen. Für dieses Projekt, das ich erwähnt habe (geschrieben in Java + Spring Boot), haben wir vier Haupttypen von Docs identifiziert: 1. Client Specs Idealerweise sind sie reich an allgegenwärtiger Sprache und liefern code-agnostic Beschreibungen von Geschäftsfällen - mit anderen Worten, alles, was ein Ingenieur braucht, um das Problem wirklich zu verstehen. Leider werden diese Dokumente oft irgendwo in Confluence gespeichert, mit dem Team zu Beginn eines Projekts geteilt und dann fast nie wieder aktualisiert. Machen Sie mich nicht falsch: Diese Dokumente Wichtig ist. sind Aber Spezifikationen entwickeln sich, Fristen betonen jeden, und diese originalen Dokumente werden langsam, aber sicher zu einem veralteten Fundament. Das Wissen über sich verändernde Anforderungen, Edge-Fälle und Projektpivots lebt am Ende im Code - oder noch schlimmer! - in den Köpfen von Senior-Entwicklern. Um dies zu lösen, haben wir aufgehört, Spezifikationen in zufälligen Word-Dateien oder Confluence-Seiten zu schreiben, die dazu bestimmt sind, vergessen zu werden, und sie so nah wie möglich an die Frontlinie gebracht: the code repository. Wir fingen an, sie als Markdown-Dateien (.md) innerhalb des Repos zu speichern, normalerweise in einem Docs / Ordner. In großen Mikroservice-Umgebungen können diese Dokumente sogar ein dediziertes Repository als Git-Submodul rechtfertigen. Für weitere Lesungen über Submodule empfehle ich diesen Blogbeitrag - . Link 2. README – The Front Door for Humans Wenn Client-Spezifikationen die Enzyklopädie sind, ist README die Haustür. und dennoch ist es eines der am meisten übersehenen Stücke der Dokumentation in Softwareprojekten. Ironisch ist, dass fast jede Versionskontrollplattform - GitHub, GitLab, Bitbucket - automatisch das README auf der Hauptprojektseite wiedergibt. Es ist das erste, was jeder Entwickler sieht, wenn er in das Repository landet. Ein gutes README ist nicht optional. Es ist das einzelne Dokument, das am wahrscheinlichsten tatsächlich gelesen wird, weil es erfordert Und weil es an der Wurzel des Repos sitzt, aktualisieren Entwickler es eher, während sie an dem Code arbeiten. zero clicks Ein gut geschriebenes README sollte die wichtigsten Fragen beantworten, die ein Entwickler innerhalb der ersten Minuten nach der Begegnung mit einem Projekt hat: 
 
 
 
 
 
 
 Was macht dieser Dienst/Projekt/Komponente? - eine prägnante Zweck- und Kontextaussage - kein Marketingfluss. Wie kann ich es lokal ausführen? - Laufzeitanweisungen, Umgebungsvariablen, Abhängigkeitseinstellungen und alle projektspezifischen Befehle. Wie teste ich es? - Einheitstests, Integrationstests, Testdaten-Setup und alle Test-bezogenen Tools. Wie ist das Projekt strukturiert? - eine kurze Erklärung des Verzeichnislayouts, der Schlüsselmodule und wo die wichtigen Teile des Codes zu finden sind. Deployment-Skripts, CI/CD-Notizen, erforderliche Berechtigungen oder Nuancen der Plattform. Wo kann ich weiterlesen? - Links zu generierten Docs, Architekturnoten, API-Referenzen und zentralisierten Designdokumenten. README ist das Tor zum Projekt. Es setzt Erwartungen, verkürzt die Onboarding-Zeit und gibt jedem Ingenieur – neuen oder erfahrenen – einen klaren Orientierungspunkt. 3. JavaDocs – Docs That The Compiler Annoys You Into Maintaining JavaDocs - in der Regel unsichtbar, oft vergessen, aber absolut notwendig, wenn etwas bricht. In der Praxis fällt die Dokumentation von Java-Projekten oft in zwei Extreme: entweder oder Weil „der Code sich selbst dokumentiert.“ Die Wahrheit liegt wie immer irgendwo in der Mitte. over-commenting every trivial line no comments at all Für unser Projekt haben wir eine bewusste Entscheidung getroffen, zu dokumentieren Das bedeutete: only what was genuinely necessary 
 
 
 
 
 mit allgegenwärtiger Sprache, so dass Domain-Begriffe genau mit dem übereinstimmen, was in den Business-Spezifikationen war erklären, warum nicht offensichtliche Entscheidungen, nicht das, was der Code bereits enthüllt Dokumentation von Kerndomänenklassen, Schnittstellen und komplexen Workflows Vermeiden von Kommentarwänden, die den Methodennamen einfach in verboser Form wiederholen JavaDocs dienen, wenn sie richtig verwendet werden, als die Mikro-Level-Dokumentation, die die Absicht klärt, ohne den Code zu verstopfen. 
 
 Der Compiler beschwert sich tatsächlich, wenn sie aus der Synchronisierung herauskommen. Wenn Sie einen Parameter umbenennen, aber den JavaDoc-Tag vergessen haben, erinnert Sie das Build daran. Wenn Sie eine Methode löschen, aber veraltete Kommentarreferenzen hinterlassen, leuchtet die IDE wie ein Weihnachtsbaum auf. Diese sanfte Reibung ist genau der Grund, warum JavaDocs dazu neigen, genauer zu bleiben als andere Formen der Dokumentation - sie sind ärgerlich zu vernachlässigen. Um alles zentralisiert zu halten und „Dokumentationsinseln“ zu vermeiden, haben wir auch . Doxygen Doxygen ist ein weit verbreitetes Dokumentationsgenerator-Tool in der Softwareentwicklung.Während es hauptsächlich in der C++-Community verwendet wird, haben wir es verwendet, um die JavaDocs in eine konsistente, durchsuchbare Referenz zu aggregieren - eine HTML-Seite.Es hat eine Reihe von Funktionen, die JavaDoc nicht anbietet, z. B. die Klassendiagramme für die Hierarchien und den Kooperationskontext, mehr Zusammenfassungsseiten und vieles mehr. Dies gab uns eine saubere, einheitliche Ansicht der gesamten Codebase, ohne auf zerstreute IDE-Tipps zu verlassen. 4. Clean Code – The Documentation You Don’t Need to Maintain Schließlich ist die am meisten unterschätzte Form der Dokumentation auch die, die Entwickler am wenigsten respektieren, bis sie sie wirklich brauchen: clean code. Kommentare Alter. Specs drift. READMEs ignoriert werden. JavaDocs können stagnieren. Aber gut geschriebener Code – klar, absichtlich und ausdrucksstark – der Dokumentation. ist Wie Onkel Bob berühmt sagte, „Sauberer Code liest wie gut geschriebene Prosa.“ In der Praxis bedeutet das: 
 
 
 
 
 
 
 Klassen und Methoden mit Namen, die ihren Zweck offenbaren Funktionen, die eine Sache tun und sie gut machen Die Domain-Terminologie wird überall konsequent verwendet Keine Klugheit für sich selbst Kein „überraschendes Verhalten“ versteckt in Nebenwirkungen keine unnötig tiefe Abstraktionen, die einen PhD erfordern zu verstehen Sauberer Code ist das einzige Artefakt, das garantiert überlebt Refaktoren, Sprints, Personalumsatz und organisatorisches Chaos. Das Verhalten des Systems. is Eine einfache Regel entstand für uns im Laufe der Zeit: If you need a paragraph of comments to explain a method, the real problem is the method. Wenn der Code ausdrucksstark ist, wird alles andere einfacher → JavaDocs werden leichter und konzentrierter → das README schrumpft, weil das Onboarding offensichtlich wird → Spezifikationen werden klarer, weil das Domain-Modell das Business-Vokabular widerspiegelt. Sauberer Code beseitigt nicht die Notwendigkeit von Dokumentation; es Das ist. Anker Es stellt sicher, dass alle anderen Formen der Dokumentation - Specs, READMEs, JavaDocs - die Wahrheit bestätigen, anstatt die unklaren Implementierungen zu kompensieren. Schließlich ist sauberer Code die Dokumentation, die keine Wartung, keine CI-Integration und kein Tooling erfordert. Bringing It All Together — A Living Documentation Pipeline Bringing It All Together – Eine lebendige Dokumentationspipeline Nachdem wir verfeinert haben, wie wir die Dokumentation geschrieben haben, war der letzte Schritt, sicherzustellen, dass sie nicht nur erstellt wurde – sondern kontinuierlich geliefert und immer zugänglich ist. . living documentation portal Da wir wollten, dass unsere Dokumente so nah wie möglich an unseren Code leben, entschieden wir uns, alles durch , die uns eine mühelose, versionskontrollierte Hosting-Lösung direkt an die Codebase gebunden gab. Github Pages ist nicht speziell für Github (GitLab zum Beispiel hat auch GitLab-Seiten) - es ist ein weiteres sauberes Feature der beliebten Versionskontrollsysteme, die ich für weitere Lesung empfehlen - . GitHub Pages Link Um alles in eine Reihe kohärenter Seiten zusammenzufassen, haben wir Sphinx. Sphinx ist ein leistungsstarker Dokumentation Generator in Python geschrieben. Es nimmt Quelldateien in reStructuredText oder Markdown geschrieben und übersetzt sie in verschiedene Ausgabeformate, einschließlich HTML, PDF und ePub. Sphinx handelte mit der Struktur, Navigation und Theming. Doxygen fütterte Sphinx mit automatisch generierten JavaDocs mit der Inzwischen diente das Root README als unmittelbarer Einstiegspunkt für Entwickler, die das Repository erforschen und nahtlos in die generierte Dokumentationswebsite verlinken. Atmen Jede Verschmelzung in den Hauptteil löste eine CI-Arbeit aus, die die Dokumente neu aufbaute, um sicherzustellen, dass das Portal die neuesten Codeänderungen, API-Updates und Designentscheidungen widerspiegelte. Nichts lebte isoliert. Nichts erforderte manuelle Synchronisierung. Dadurch wurde unsere Dokumentation von einem statischen Artefakt zu einem kontinuierlich aktualisierten Ökosystem, das die Entwickler tatsächlich verwendeten, weil es direkt in ihren täglichen Workflow integriert wurde und direkt neben dem Code lebte. Conclusion — Documentation Is Our Responsibility, Not Our Burden Schlussfolgerung – Dokumentation ist unsere Verantwortung, nicht unsere Last Am Ende des Tages ist das Schreiben von Dokumentation nicht optional. Es ist Teil unserer Arbeit als Ingenieur-Profis. zukünftige Teamkollegen hängen davon ab. Das Onboarding hängt davon ab. Wartung, Zuverlässigkeit und sogar architektonische Klarheit hängen davon ab. Indem wir Dokumente in der Nähe des Codes halten, alles automatisieren, was automatisiert werden kann, und auf intelligente Tools wie Markdown, JavaDocs, Doxygen und Sphinx vertrauen, entfernen wir die Reibung, die normalerweise die Dokumentationsanstrengungen tötet. Wenn wir Systeme bauen, die Entwickler dazu ermutigen, Dokumente so einfach zu aktualisieren, wie sie Code schreiben, profitieren alle: das Team, das Produkt und vor allem die arme Seele, die das Projekt sechs Monate später erbt. Gute Dokumentation macht uns nicht weniger faul. Es macht einfach faul kompatibel mit dem Aufbau großer Software.

The is an opinion piece based on the author’s POV and does not necessarily reflect the views of HackerNoon.

Every

Front

Read My Stories

Dieses Audio ist in der Originalsprache der Geschichte produziert!

Wenn Ihre Dokumentation zwei Klicks benötigt, um zu öffnen, kongrats - es ist bereits veraltet

About Author

KOMMENTARE

Hängeetiketten

DIESER ARTIKEL WURDE VORGESTELLT IN

Related Stories

HackerNoon Decoded 2024: Wir feiern die Community unserer Technologieunternehmen!

Welcome to HackerNoon Decoded: The Best of 2024 Tech Blogging

Starting 2025 with New Features: Settings Dashboard, HackerNoon Decoded, Updated Search UI, and More

HackerNoon Decoded 2024: Wir feiern unsere Produktmanagement-Community!

HackerNoon Decoded 2024: Wir feiern die Community unserer Technologieunternehmen!

Welcome to HackerNoon Decoded: The Best of 2024 Tech Blogging

Starting 2025 with New Features: Settings Dashboard, HackerNoon Decoded, Updated Search UI, and More

HackerNoon Decoded 2024: Wir feiern unsere Produktmanagement-Community!

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps