Warum gibt es keine Codeübersichten für Open-Source-Projekte? [geschlossen]

Es gibt sehr komplexe Open-Source-Projekte, und für einige von ihnen könnte ich meiner Meinung nach einen Beitrag leisten, und ich wünschte, ich könnte es, aber die Eintrittsbarriere ist aus einem einzigen Grund zu hoch: für das Ändern einer Codezeile nach dem anderen großes projekt man muss alles verstehen.

Sie müssen nicht den gesamten Code lesen (auch wenn Sie ihn lesen, reicht er nicht aus) und verstehen, was jede einzelne Zeile tut und warum. Der Code ist wahrscheinlich modularisiert und unterteilt, sodass Abstraktionen vorhanden sind Selbst dann müssen Sie sich einen Überblick über das Projekt verschaffen, damit Sie wissen, wo sich die Module befinden, wo sich ein Modul mit dem anderen verbindet, was genau jedes Modul macht und warum und in welchen Verzeichnissen und Dateien all diese Dinge geschehen.

Ich bezeichne diese Code-Übersicht als den Namen eines Abschnitts, den Open-Source-Projekte auf der Website oder in der Dokumentation haben könnten, um Außenstehenden ihren Code zu erklären. Ich denke , es würde profitieren potenziellen Beitrag , da sie Orte zu identifizieren , wäre in der Lage , wo sie bauen könnten, die eigentlichen primären Programmierer beteiligt, da sie wäre in der Lage zu sein , während alles schreiben, ihre Meinung zu reorganisieren, und würde dazu beitragen , die Benutzer , wie sie würden Helfen Sie dabei, aufgetretene Fehler besser zu verstehen und zu melden, und werden Sie möglicherweise sogar Mitwirkende.

Trotzdem habe ich noch nie eine dieser "Codeübersichten" gesehen. Warum? Gibt es solche Dinge und ich vermisse sie? Dinge, die den gleichen Job machen, den ich beschreibe? Oder ist dies eine völlig nutzlose Idee, da jeder außer mir Projekte mit Tausenden von Codezeilen leicht verstehen kann?

Weil es ein zusätzlicher Aufwand ist, ein solches Dokument zu erstellen und zu pflegen, und zu viele Menschen die damit verbundenen Vorteile nicht verstehen.

Viele Programmierer sind keine guten technischen Redakteure (obwohl es viele sind); Sie schreiben nur selten Dokumente, die ausschließlich für den menschlichen Verzehr bestimmt sind. Deshalb haben sie keine Übung und tun dies nicht gerne. Das Erstellen einer Codeübersicht kostet Zeit, die Sie nicht für das Codieren ausgeben können, und der anfängliche Nutzen eines Projekts ist immer größer, wenn Sie sagen: "Wir unterstützen alle drei Codierungsvarianten" und nicht "Wir haben wirklich gute Erklärungen für unseren Code!" Die Vorstellung, dass ein solches Dokument mehr Entwickler anzieht, damit auf lange Sicht mehr Code geschrieben wird, ist für sie nicht gerade fremd , wird jedoch als ungewisses Spiel empfunden. Wird dieser Text wirklich den Unterschied ausmachen, ob ein Mitarbeiter hängen bleibt oder nicht? Wenn ich jetzt weiter programmiere , Mach das Ding fertig.

Ein Code-Übersichtsdokument kann auch dazu führen, dass sich Menschen defensiv fühlen. Es ist schwierig, übergeordnete Entscheidungen zu beschreiben, ohne das Gefühl zu haben, sie rechtfertigen zu müssen, und sehr oft treffen Menschen Entscheidungen ohne einen Grund, der "gut genug" klingt, wenn sie tatsächlich selbst geschrieben sind. Es gibt auch einen Effekt im Zusammenhang mit dem oben genannten: Da das Aktualisieren des Texts an den sich ändernden Code zusätzlichen Aufwand verursacht, kann dies umfassende Änderungen am Code verhindern. Manchmal ist diese Stabilität eine gute Sache, aber wenn der Code wirklich eine Neuschreibung auf mittlerer Ebene benötigt, wird er zur Verbindlichkeit.

Die trockene, raue Wahrheit?

Die Dokumentation wird nicht erstellt, da Projekte darauf verzichten können.

Sogar Open Source-Projekte sind häufig einem harten Wettbewerb ausgesetzt. Die meisten solcher Projekte beginnen nicht mit großen Schultern, sie beginnen mit einer guten Idee, oft mit einer Ein-Mann-Idee.

Daher können sie sich die Zeit und die Kosten für die Einstellung menschlicher Dokumentatoren nicht leisten, selbst wenn sie eine kostenlose Zusammenarbeit anbieten. Ein dokumentiertes Projekt, infact, hat in der Regel zuerst mehrere Anfangsiterationen durchlaufen. Es beginnt oft mit 1-3, vielleicht schreiben 5 Leute ihre Idee auf und zeigen sie der Welt als Proof of Concept. Wenn sich die Idee als gut erweist, fragen "Follower" in der Regel nach Erweiterungen, neuen Optionen, Übersetzungen ... Zu diesem Zeitpunkt ist der Code noch ein Prototyp, in der Regel mit fest codierten Optionen und Nachrichten.

Nicht alle Open Source-Projekte gehen über diese Phase hinaus, sondern nur diejenigen, die die "kritische Masse" durchbrechen, die erforderlich ist, um das öffentliche Interesse zu wecken. Darüber hinaus muss einer der ersten Entwickler "groß und weit denken" und Erweiterungen und so weiter planen. Er könnte genauso gut das Projekt "Evangelist" und manchmal auch "Projektmanager" werden (manchmal sind es andere Leute). Dies ist ein notwendiger Schritt, um das Projekt vom Proof of Concept zu einer in der Branche etablierten Realität zu machen.

Selbst dann kann der Projektmanager entscheiden, keine Dokumentation zu erstellen.

Ein dynamisches, wachsendes Projekt würde sowohl verlangsamt als auch die Dokumentation hinter dem Code zurückbleiben, während es wirklich hart verbessert wird, um Übersetzungen, Optionen, Plug-in-Manager zu implementieren ...

Was normalerweise passiert ist:

1. Es wird ein kurzes Einführungsdokument erstellt, in dem beschrieben wird, was das Projekt ist und wohin es führen soll (die berühmte "Roadmap").
2. Wenn möglich, wird eine API entwickelt und diese als "dokumentierter Code" über den Großteil des zugrunde liegenden Codes gewählt.
3. Vor allem die API aber auch der andere Code werden neu formatiert und "PHPdoc" / "Javadoc" etc. spezielle Kommentare hinzugefügt. Sie bieten einen vernünftigen Kompromiss zwischen Zeitaufwand und Belohnung: Selbst ein bescheidener Programmierer weiß normalerweise, wie man einen Einzeiler schreibt, der seine Funktionen beschreibt, Parameter werden ebenfalls "automatisch" dokumentiert, und das Ganze ist an den zugehörigen Code gebunden, wodurch Dokumentation vermieden wird. Desynchen "und verzögerte Entwicklung.
4. Meist wird ein Forum erstellt. Es handelt sich um ein leistungsstarkes soziales Medium, in dem sich Endbenutzer und Programmierer unterhalten können (und unter Gleichgesinnten, möglicherweise nur in Unterforen für Entwickler). Dies ermöglicht, dass eine Menge Wissen langsam auftaucht und von der Community zusammengestellt wird (lesen Sie: Das Entwicklerteam nicht belasten). FAQs und HOWTOs.
5. In wirklich großen Projekten wird auch ein Wiki erstellt. Ich nenne "große Projekte", weil sie oft genug Anhänger haben, um ein Wiki zu erstellen (ein Entwickler tut es) und es dann tatsächlich über die "bloßen Knochen" hinaus zu füllen (die Community tut es).

Übersichtsdokumente, wie Sie sie beschreiben, sind selbst bei kommerziellen Projekten selten. Sie erfordern zusätzlichen Aufwand mit geringem Wert für die Entwickler. Entwickler neigen auch dazu, keine Dokumentation zu schreiben, es sei denn, sie müssen es wirklich. Einige Projekte haben das Glück, Mitglieder zu haben, die sich mit technischen Texten auskennen und daher eine gute Benutzerdokumentation haben. Entwicklerdokumentation, falls vorhanden, wird wahrscheinlich nicht aktualisiert, um Codeänderungen widerzuspiegeln.

Jedes gut organisierte Projekt hat einen Verzeichnisbaum, der relativ selbsterklärend ist. Einige Projekte dokumentieren diese Hierarchie und / oder die Gründe, aus denen sie ausgewählt wurde. Viele Projekte folgen relativ standardmäßigen Codelayouts. Wenn Sie also eines verstehen, verstehen Sie das Layout anderer Projekte, die dasselbe Layout verwenden.

Um eine Codezeile zu ändern, benötigen Sie ein begrenztes Verständnis des umgebenden Codes. Sie sollten niemals die gesamte Codebasis verstehen müssen, um dies zu tun. Wenn Sie eine vernünftige Vorstellung von der Art der fehlerhaften Funktion haben, ist es häufig möglich, die Verzeichnishierarchie relativ schnell zu durchlaufen.

Um eine Codezeile zu ändern, müssen Sie die Methode verstehen, in der sich die Zeile befindet. Wenn Sie das erwartete Verhalten der Methode verstehen, sollten Sie in der Lage sein, Korrekturen oder Erweiterungen an der Funktionalität vorzunehmen.

Für Sprachen, die Gültigkeitsbereiche bereitstellen, können Sie Methoden mit privatem Gültigkeitsbereich überarbeiten. In diesem Fall müssen Sie möglicherweise den Anrufer sowie die Refactor-Methode (n) ändern. Dies erfordert ein breiteres, aber immer noch begrenztes Verständnis der Codebasis.

In meinem Artikel Hinzufügen von SHA-2 zu tinyca finden Sie ein Beispiel dafür, wie solche Änderungen vorgenommen werden können. Ich verstehe den Code, der zum Generieren der Schnittstelle verwendet wird, nur sehr eingeschränkt.

Gibt es solche Dinge und ich vermisse sie? Dinge, die den gleichen Job machen, den ich beschreibe?

Es gibt ein ausgezeichnetes Buch mit dem Titel " Die Architektur von Open Source-Anwendungen" , das detaillierte Beschreibungen einer Vielzahl von hochkarätigen Open Source-Softwareprojekten enthält. Ich bin mir jedoch nicht sicher, ob es genau die Rolle erfüllt, die Sie sich vorstellen, da es sich meiner Meinung nach in erster Linie um Entwickler handelt, die beim Erstellen ihrer eigenen Anwendungen nach Mustern suchen, und nicht um neue Mitwirkende an den im Buch vorgestellten Projekten (obwohl ich sicher bin, dass es dort hilfreich sein könnte).

Denn es gibt weit mehr Open-Source-Programmierer als Open-Source-Technische Redakteure.

Die Dokumentation benötigt Wartung und Zeit, um auf dem neuesten Stand zu bleiben. Je umfangreicher die Dokumentation, desto mehr Zeit wird benötigt. Und Dokumentation, die nicht mit dem Code synchronisiert ist, ist schlimmer als nutzlos: Sie führt in die Irre und verbirgt sich, anstatt zu enthüllen.

Eine gut dokumentierte Codebasis ist besser als eine weniger dokumentierte, aber die Dokumentation kann leicht so lange dauern, wie der Code zuerst geschrieben wird. Ihre Frage ist also, ist es besser, eine gut dokumentierte Codebasis oder eine doppelt so große Codebasis zu haben? Sind die Kosten für die Aktualisierung der Dokumentation bei jeder Codeänderung die Beiträge zusätzlicher Entwickler wert?

Versandcode gewinnt. Eine Reduzierung des Aufwands für andere Dinge als den Versandcode kann dazu führen, dass der Code häufiger versendet wird und mit höherer Wahrscheinlichkeit versendet wird, bevor ihm die Ressourcen ausgehen.

Das heißt nicht, dass es neben der Schifffahrt auch um die Dinge geht. Durch die Dokumentation wird das Projekt aufgewertet, und bei einem ausreichend großen Projekt sind die Verbindungskosten für das Hinzufügen eines weiteren Entwicklers möglicherweise viel höher als für das Hinzufügen eines Dokumentators. Wie bereits erwähnt, kann die Dokumentation die Investition in das Projekt erhöhen (indem sie neuen Programmierern den Einstieg erleichtert).

Nichts verkauft sich jedoch so gut wie der Erfolg: Ein Projekt, das nicht funktioniert oder nichts Interessantes tut, zieht auch selten Entwickler an.

Die Dokumentation einer Codebasis ist eine Form der Metaarbeit. Sie können viel Zeit damit verbringen, ausgefallene Dokumente zu schreiben, die eine Codebasis beschreiben, die nicht viel Wert hat, oder Sie können Zeit damit verbringen, Dinge zu erstellen, die die Konsumenten Ihrer Codebasis wollen, und Ihre Codebasis wertvoll machen.

Manchmal macht es die, die die Aufgabe besser erledigen, schwieriger. Entweder aufgrund eines höheren Maßes an Engagement für das Projekt (stundenlanges Erlernen der Architektur) oder aufgrund von Vorurteilen in Bezug auf Fähigkeiten (wenn Sie bereits ein Experte für verwandte Technologien sind, wird das Aufstehen schneller sein, sodass die Barriere des Mangels besteht Eine solche Dokumentation ist weniger wichtig: So kommen mehr Experten zum Team und weniger Anfänger.

Aus den oben genannten Gründen dürften die derzeitigen Entwickler Experten auf dem Gebiet des Codes sein. Das Schreiben einer solchen Dokumentation hilft ihnen nicht viel, die Codebasis zu verstehen, da sie bereits über das Wissen verfügen, sondern nur anderen Entwicklern. Ein Großteil der Open-Source-Entwicklung basiert darauf, dass der Entwickler mit dem Code "kratzt": Mangelnde Dokumentation, die bereits sagt, was der Entwickler weiß, juckt selten.

Neben zusätzlichen Aufwand zu sein , einige Open - Source - Projekt lähmen ihre Dokumentationen zu Zweck, um Arbeitsplätze zu erhalten freelancing für ihre Maintainer (zu etwas umzusetzen oder zu halten , Schulungen). Sie haben nicht nur keinen Überblick über den Code, sondern ihre API und Tutorials sind auch schlecht oder es fehlen viele Dinge.

Um nur eines recht populär zu nennen: bluez. Viel Glück beim Finden eines guten Tutorials, außer zum Scannen nach Geräten in der Nähe.