Wie können Open Source-Projekte ohne Dokumentation zu Design oder Architektur erfolgreich sein?

11

Ich möchte meine Programmierkenntnisse verbessern, indem ich berühmte Open-Source-Projekte studiere, aber ich finde es leicht, mich zu verlaufen, wenn ich einfach in ihren Quellcode springe.

Daher habe ich mich entschlossen, die Dokumentation zu Design oder Architektur (z. B. UML-Diagramme) zu lesen, um zunächst eine allgemeine Vorstellung von der Organisation des Codes zu erhalten. Zu meiner Überraschung kann ich jedoch keine Architekturdokumentation für große Open Source-Projekte wie Hibernate, Spring, ASP.NET MVC, Rails usw. finden.

Ich habe mich also gefragt: Wie kann ein Open Source-Projekt erfolgreich sein, wenn neue Entwickler keine Architektur- / Designdokumentation zum Lesen haben oder wenn der Projektmanager nur den Quellcode geöffnet, aber seine Dokumentation geschlossen hat?

TomCaps
quelle
3
"die meisten"? Können Sie dies mit konkreten Statistiken belegen? Wie viele hast du gelesen? Wie viele sind es? Wie vielen fehlte eine entsprechende Dokumentation? Wenn Sie keine Zahlen haben, entfernen Sie bitte Wörter wie "die meisten" und ersetzen Sie sie durch echte Fakten, basierend auf dem, was Sie wirklich gefunden haben. Bitte schreiben Sie auch "I" groß, wenn Sie sich auf sich selbst beziehen.
S.Lott
@ S.Lott Sorry für das subjektive "meiste". Ich bin ein Neuling in der Softwareindustrie. Ich versuche, auf der Projektwebsite oder im Code-Repository nach Dokumenten zu suchen, von denen ich während der College-Schule gehört habe (wie UML-Diagramm, Flussdiagramm, Kurzentwurfsdokument, Detaled Design Doc usw.), aber ohne Glück. nur um ein Benutzerhandbuch zu finden. Können Sie mir bitte eine gängige Methode zur Suche in ihren Desgin- / Archiecture-Dokumenten beibringen?
TomCaps
1
Bitte entfernen Sie "Viele". Das ist genauso falsch wie die meisten. Bitte aktualisieren Sie die Frage, um speziell die spezifischen Open Source-Projekte aufzulisten, denen die spezifische Dokumentation fehlt, die Sie sehen möchten. Bitte seien Sie präzise und spezifisch. Bitte seien Sie nicht subjektiv und vage.
S.Lott
Ich vermute, dass der Grund, warum ASP.NET MVC keine UML-Diagramme enthält, darin besteht, dass Visual Studio sie aus dem Quellcode erstellen kann.
user16764
5
Sie arbeiten unter der falschen Annahme, dass "Enterprisy" eine gute Sache ist. Was Sie im College über Design gelernt haben, sind alles Lügen: UML hat absolut keinen Wert. Wenn Sie ein Projekt erstellen, brauchen Sie nur eine allgemeine Vorstellung davon, was es tun soll, und die Bereitschaft, es wegzuwerfen, wenn Sie es beim ersten Mal falsch machen. Bei einem vorhandenen Projekt reicht es normalerweise aus, nur den Hauptheader zu überfliegen, um eine gute Vorstellung vom Projektlayout zu erhalten.
o11c

Antworten:

10

Warum kann ein Open Source-Projekt erfolgreich werden, wenn neue Entwickler kein Architektur- / Designdokument zum Lesen haben?

Es wird ausnahmslos davon ausgegangen, dass Sie wissen, was Sie tun, und ein einigermaßen intimes Verständnis dafür haben, was Sie sehen (und erwarten).

Wenn Sie sich beispielsweise den PHP-Code des Symfony-Frameworks ansehen, müssen Sie bereits über die Abhängigkeitsinjektion, Ereignisse, das Modell- / Ansichts- / Controller-Muster usw. Bescheid wissen.

Wenn Sie in den C-Code des Linux-Kernels eintauchen, wird davon ausgegangen, dass Sie in Bezug auf Modularität, Signale, Prozesse, Threads und was nicht realistisch kompetent sind. Es wird auch erwartet, dass Sie den ganzen Tag hexadezimal essen und mit einer riesigen Schaufel durch Kernkippen graben können.

Die Betreuer werden sich nicht die Mühe machen, die Architektur zu dokumentieren, weil es sich um sachliche Dinge handelt. Gelegentlich finden Sie im Quellbaum einen Überblick darüber, was wo liegt. Typischerweise macht die Art und Weise, wie der Quellbaum organisiert ist, die Dinge selbsterklärend.

Kurz gesagt, wenn Ihnen die Fähigkeiten fehlen, die die Betreuer erwarten, wenn Sie in ihren Code schauen, werden Sie wahrscheinlich Dinge durchforsten, die weit über Ihrer Gehaltsstufe liegen. Machen Sie sich zuerst mit den Konzepten vertraut - Was ist das MVC-Modell? Was ist Abhängigkeitsinjektion? Dann tauchen.

Denis de Bernardy
quelle
1
Wenn Sie sich Mailinglisten ansehen, hat der Linux-Kernel eine ausführliche Diskussion über die Architektur, wenn jemand ein Problem hat oder etwas ändern möchte. Es gibt auch einige Dokumente darüber - allerdings nicht im Kernel-Quellbaum.
edA-qa mort-ora-y
17

Die meisten erfolgreichen Open Source-Projekte wurden erfolgreich, weil das Programm in erster Linie beeindruckend war oder etwas tat, was zu diesem Zeitpunkt kein anderes Programm konnte. Das bedeutet nicht unbedingt, dass die Quelle gut dokumentiert ist, da die Programmierer, die das Projekt begonnen haben, den Code gut genug kennen, um ihn nicht zu benötigen. Es ist eine bedauerliche Tatsache, dass Open Source-Projekte nicht gut dokumentiert sein müssen. Es muss entweder ein gutes Programm oder ein mittelmäßiges Programm sein, aber gut dokumentiert, damit Programmierer Interesse daran zeigen können.

Neil
quelle
In meinem Unternehmen ist es ein Anforderungsverfahren, dass Entwickler ein detailliertes Designdokument bereitstellen müssen, bevor sie genehmigt werden. Schreiben Sie Code in ein Projekt. Ist dieses Verfahren für Open Source-Projekte abnormal?
TomCaps
5
@ TomCaps Ich denke, der Hauptgrund dafür, dass so wenige FOSS-Projekte über eine umfangreiche Dokumentation verfügen, ist recht einfach: Wenn Sie ein kleines Programm schreiben, um einen Bedarf zu lösen, den Sie haben, ist es wahrscheinlich, dass Sie als Entwickler keine Dokumentation benötigen Sie möchten Ihre Zeit damit verbringen, das Programm zu verbessern, anstatt Dokumentationen zu schreiben, die garantiert nicht einmal für irgendjemanden nützlich sind (was ist, wenn das Projekt nur von Entwicklern verwendet wird?). Es ist keine bewährte Methode, aber bei vielen FOSS-Projekten fehlt die Entwicklerzeit.
Jeff Welling
5
@ TomCaps: Dieses Verfahren ist für die meisten Unternehmen, die ich kenne, abnormal ...
Treb
1
Die meisten Open Source-Projekte sind keine Unternehmen. Sie überlegen, was passiert, wenn es ein Projekt gibt, für dessen Bau ich bezahlt werde, mit einer Frist und einem Budget. Wenn Sie eine Menge Leute haben, die programmieren, um ein Bedürfnis zu befriedigen, das sie haben, oder zum Spaß, und es kein Budget oder keinen Kunden gibt, haben Sie solche Dinge nicht.
Elin
1
@ TomCaps - Jeder, der Open Source-Software schreibt, kann genau das tun, was er möchte. Einige Projekte (z. B. die Apache-Familie) haben Regeln und Richtlinien für jeden, der Code festschreibt, und manchmal enthält dies Dokumentationsstandards usw. Außerdem würde ich den Wert eines "Detail-Design-Dokuments" in Frage stellen, da dies Sie ausnahmslos in ein physisches Design einschließt, das (in meine persönliche Erfahrung) ist normalerweise nicht optimal. Eine detaillierte Beschreibung dessen, was das Programm tun soll, lässt dem Entwickler die Möglichkeit, die Implementierung zu optimieren und kreative Strategien auf die Lösung anzuwenden.
James Anderson
12

Da Open Source-Entwickler in der Regel talentiert sind und auch Projekte in ihrem Fachgebiet auswählen, haben sie bereits "Dokumentation" in ihren Schädeln. Mit wenig Übertreibung ist eine gründliche Dokumentation nur erforderlich, wenn Ihnen eine der folgenden Angaben fehlt: o)

Um ehrlich zu sein, lese ich "Dokumentation" nicht wirklich, wenn ich mit unbekannter Codebasis konfrontiert bin. Eine kurze Einführung, vielleicht ein paar konzeptionelle Skizzen und direkt in den Code! Experimentieren Sie, versuchen Sie kleine Änderungen. Funktioniert perfekt für gut gestalteten Code. Wenn ich mit schrecklichen Problemen konfrontiert bin, ist es am besten, sie Stück für Stück umzugestalten, um die Klarheit zu verbessern (idealerweise mithilfe von Unit-Tests).

Ein weiterer Grund könnten einfache organische Designwurzeln dieser Projekte sein. Architektur ist dann in den Köpfen der Entwickler eher eine weiterentwickelte Vision als eine angegebene "dokumentierte" Einheit.

Beschädigen
quelle
8

Der Grund, warum solche Dokumente oft nicht existieren, ist ziemlich einfach: Programmierer programmieren gerne, schreiben keine Dokumentation. Besonders bei Open-Source-Projekten, die Entwickler häufig in ihrer Freizeit beitragen.

Grundsätzlich macht das Schreiben von Dokumentation keinen Spaß. Und wenn sie nicht dafür bezahlt werden, wer möchte dann seine Freizeit damit verbringen, etwas zu tun, das keinen Spaß macht?

GroßmeisterB
quelle
Bei einigen großen Open-Source-Projekten (GCC, Linux-Kernel, Firefox, Qt, ...) werden die meisten (oder ein erheblicher Teil) ihrer Mitwirkenden für die Arbeit (Vollzeit oder Halbzeit) an dem Projekt bezahlt. Selbst wenn sie für freie Software bezahlt werden, schreiben sie nicht viel Dokumentation
Basile Starynkevitch