- esbuild und Redis sind Beispiele für Codebasen mit hervorragender Dokumentation.
- Über README, Changelog, Architekturdokumente und Code-Kommentare können selbst neue Nutzer die Struktur der Codebasis, ihre Funktionsweise und die Gründe dahinter verstehen.
- Sie eignen sich als gute Fallstudien für Entwickler, die die Dokumentation von Code und Softwarearchitektur verbessern möchten.
Warum gute Dokumentation wichtig ist
- Beim Schreiben von Software ist gute Dokumentation essenziell, besonders wenn andere die Codebasis ansehen oder dazu beitragen oder wenn man selbst später wieder darauf zurückgreift.
- Nutzer von Software stoßen oft wegen fehlender Dokumentation auf Schwierigkeiten.
- Wenn man zu einer Codebasis beiträgt, kann man mit besserer Dokumentationsqualität schneller beitragen.
- Die Qualität der Dokumentation beeinflusst direkt oder indirekt die Erfahrung von Autor, Mitwirkenden oder Nutzern.
- Die Vorteile guter Dokumentation sind vielfältig: Zeitersparnis, mehr externe Beiträge zu Open-Source-Projekten, eine Aufzeichnung früherer Entscheidungen, bessere Zugänglichkeit für mehr Nutzer, strukturierteres Denken und das Erkennen von Problemen.
Dokumentation bei esbuild
- esbuild ist ein JavaScript-Bundler von Evan Wallace.
- Das README von esbuild ist auf die Endnutzer des Tools ausgerichtet.
- Über Links zu den Hauptabschnitten der Dokumentation und einen Abschnitt "Warum?" wird kurz erklärt, warum man esbuild gegenüber anderen Bundlern wählen sollte.
- Die Architekturdokumentation von esbuild besteht im Verzeichnis
docs aus den Dateien architecture.md und development.md.
- Das Architekturdokument erklärt die Designprinzipien und enthält neben Text auch Grafiken zur Veranschaulichung von Konzepten.
- Der Changelog von esbuild ist detailliert und enthält Zusammenfassungen, ausführlichere Erklärungen sowie Beispielcode vor und nach den Änderungen.
Dokumentation bei Redis
- Redis ist eine In-Memory-Datenbank.
- Das README von Redis teilt viele der guten Eigenschaften des esbuild-README, richtet sich dabei aber sowohl an Mitwirkende als auch an Endnutzer.
- Ein Abschnitt über das Innenleben von Redis enthält das Layout des Quellcodes und Erklärungen zu wichtigen Dateien.
- Die Code-Kommentare im Redis-Quellcode liefern mehrere Absätze Erklärung zu einzelnen Codezeilen.
Fazit
- Viele Open-Source-Projekte verfügen über hervorragende Dokumentation.
- esbuild und Redis beeindrucken dabei besonders durch ihre herausragende Dokumentation.
- Dokumentation kann kurzfristig zusätzlichen Zeitaufwand verursachen, spart aber langfristig Zeit.
- Bei Projekten, die von vielen Menschen genutzt oder mitentwickelt werden, sollte man es überdenken, auf Dokumentation zu verzichten.
Meinung von GN⁺
- Die Dokumentationsbeispiele von esbuild und Redis unterstreichen für Entwickler die Bedeutung von Dokumentation, um das Verständnis und die Wartbarkeit einer Codebasis zu erleichtern.
- Dokumentation ist ein zentraler Faktor, um die Nachhaltigkeit eines Projekts zu erhöhen und die Beteiligung der Community zu fördern.
- Im Fall von esbuild scheint neben der Funktion als schneller JavaScript-Bundler auch die hervorragende Dokumentation zum Wachstum des Projekts beigetragen zu haben.
- Redis hat durch Dokumentation, die das Verständnis eines komplexen In-Memory-Datenbanksystems erleichtert, einen positiven Einfluss auf die Entwickler-Community.
- Solche Beispiele können helfen, die Bedeutung von Dokumentation auch in andere Open-Source-Projekte zu tragen, und sind besonders nützlich, um angehenden Softwareingenieuren zu vermitteln, wie sie ihre eigenen Projekte dokumentieren können.
2 Kommentare
Bei esbuild ist nicht nur die
README.mdgroßartig, sondern auch die im Artikel vorgestellte Datei architecture.md ist einfach wunderschön!Hacker-News-Kommentar
Antirez, der Gründer von Redis, hat in seinem Blog einen Beitrag veröffentlicht, in dem er seine Gedanken zu Code-Kommentaren ausführlich darlegt. Er identifiziert neun Arten von Kommentaren, die in Redis verwendet werden.
Ein gut geschriebener Artikel mit konkreten Beispielen und Screenshots dazu, wie Projektdokumentation für Nutzer/Entwickler/Mitwirkende hervorragend sein kann.
Zeigt das Interesse der Maintainer an der Qualität des Repositorys.
Erinnert an die Reihe „The Architecture of Open Source Applications“. Sie enthält interessante Einsichten.
Die Dokumentation von GitLab hat den Ruf, sehr gut zu sein, aber ich musste sie selbst nicht oft nutzen. Ich frage mich, ob ihre Architekturdokumentation ebenfalls gut ist.
Auch das Postgres-Projekt legt großen Wert auf Dokumentation, README-Dateien und Code-Kommentare.
Ich bin von der Architekturdokumentation des esbuild-Projekts tief beeindruckt. Ich wünschte, in Codebasen, an denen ich früher gearbeitet habe, hätte es solche Dokumente gegeben.
Ich mag Changelogs von Open-Source-Projekten sehr. Sie sind weit professioneller und informativer als die anderer gewinnorientierter Organisationen. Kritik daran, dass die Changelogs der App der ING-Bank eher informativ als humorvoll sein sollten.
„Der größte Mangel in der heutigen Freie-Software-Community ist nicht Software, sondern der Mangel an guter freier Dokumentation, die mit freier Software mitgeliefert werden kann.“
Es wird darauf hingewiesen, dass Redis nicht mehr Open Source ist. Redis ist „Source-Available“-Software unter der Redis Source Available License v2 (RSALv2) und der Server Side Public License v1 (SSPLv1).