it-swarm.com.de

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

Es gibt sehr komplexe Open-Source-Projekte, und für einige von ihnen denke ich, ich könnte einige Beiträge leisten, und ich wünschte, ich könnte, aber die Eintrittsbarriere ist aus einem einzigen Grund zu hoch: um eine Codezeile an einer zu ändern großes projekt muss man alles verstehen.

Sie müssen nicht den gesamten Code lesen (auch wenn Sie ihn lesen, er reicht nicht aus) und verstehen, was jede einzelne Zeile tut und warum, da der Code wahrscheinlich modularisiert und unterteilt ist, sodass Abstraktionen vorhanden sind, aber Selbst dann müssen Sie eine Übersicht über das Projekt erhalten, damit Sie wissen , wo die Module sind ) wo ein Modul mit einem anderen verbunden ist, was genau jedes Modul tut und warum und in welchen Verzeichnissen und Dateien sind jedes dieser Dinge, die passieren.

Ich nenne dies 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 potenziellen Mitwirkenden zugute kommen, da sie Orte identifizieren könnten, an denen sie bauen könnten, die tatsächlichen primären Codierer , da sie in der Lage wären, beim Schreiben alles ihre Gedanken neu zu organisieren und den Benutzern zu helfen , da sie helfen würden, Fehler zu verstehen und besser zu melden, die sie erfahren und vielleicht sogar werden 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?

60
fiatjaf

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

Viele Programmierer sind keine guten technischen Redakteure (obwohl viele es sind); Sie schreiben selten Dokumente ausschließlich für den menschlichen Verzehr, deshalb haben sie keine Übung und tun es nicht gern. Das Schreiben einer Codeübersicht erfordert Zeit, die Sie nicht für das Codieren aufwenden können, und der anfängliche Nutzen für ein Projekt ist immer größer, wenn Sie sagen können: "Wir unterstützen alle drei Kodierungsvarianten "statt" Wir haben wirklich nette Erklärungen für unseren Code! " Die Vorstellung, dass ein solches Dokument mehr Entwickler anzieht, so dass auf lange Sicht mehr Code geschrieben wird, ist ihnen nicht genau fremd , wird aber wahrgenommen als ungewisses Glücksspiel; Wird dieser Text wirklich den Unterschied machen, ob man einen Mitarbeiter erwischt oder nicht? Wenn ich jetzt weiter codiere , werden wir mit Sicherheit diese Sache erledigen .

Ein Codeübersichtsdokument kann auch dazu führen, dass sich Menschen defensiv fühlen. Es ist schwer, Entscheidungen auf höherer Ebene 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 werden. Es gibt auch einen Effekt im Zusammenhang mit dem oben genannten: Da das Aktualisieren des Textes an den sich ändernden Code zusätzlichen Aufwand verursacht, kann dies umfassende Änderungen des Codes verhindern. Manchmal ist diese Stabilität eine gute Sache, aber wenn der Code wirklich eine Umschreibung auf mittlerer Ebene benötigt, wird er zu einer Haftung.

60
Kilian Foth

Die trockene, harte Wahrheit?

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

Selbst Open-Source-Projekte sind häufig einem harten Wettbewerb ausgesetzt. Die meisten dieser Projekte beginnen nicht mit großen Schultern, sondern beginnen mit einer guten Idee, oft mit einer guten Idee für einen Mann.

Als solche können sie sich die Zeit und die Kosten für die Einstellung menschlicher Dokumentatoren nicht leisten, selbst wenn sie angeboten haben, kostenlos zusammenzuarbeiten. Ein dokumentiertes Projekt, infact, hat normalerweise zuerst mehrere Anfangsiterationen durchlaufen. Es beginnt oft mit 1-3, vielleicht schreiben 5 Leute ihre neuartige Idee auf und zeigen sie der Welt als Proof of Concept. Wenn sich die Idee als gut erweist, können "Follower" dazu neigen, nach Erweiterungen, neuen Optionen, Übersetzungen ... zu fragen. Zu diesem Zeitpunkt ist der Code noch ein Prototyp, normalerweise 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 planen und so weiter. 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 bis zur branchenweit etablierten Realität auf den neuesten Stand zu bringen.

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

Ein dynamisches, wachsendes Projekt würde sowohl verlangsamt als auch die Dokumentation würde wirklich 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 erläutert wird, was das Projekt ist und wohin es führt (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. Insbesondere die API, aber auch der andere Code werden neu formatiert und "PHPdoc"/"Javadoc" usw. werden mit speziellen Kommentaren versehen. Sie bieten einen anständigen 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, und daher vermeiden sie Dokumentation. " Desyncing "und Verzögerung der Entwicklung.
  4. Meistens wird ein Forum erstellt. Es ist ein leistungsstarkes soziales Medium, in dem Endbenutzer und Programmierer miteinander sprechen können (und zwischen ihren Kollegen, möglicherweise in Unterforen "nur Entwickler"). Auf diese Weise kann langsam eine Menge Wissen entstehen und durch von der Community erstellte FAQs und HOWTOs konsolidiert werden (lesen Sie: das Entwicklerteam nicht belasten).
  5. In wirklich großen Projekten wird auch ein Wiki erstellt. Ich nenne "große Projekte", weil sie oft genug Follower haben, um ein Wiki zu erstellen (ein Entwickler tut es) und es dann tatsächlich über die "nackten Knochen" hinaus zu füllen (die Community tut es).
14
Dario Fumagalli

Übersichtsdokumente, wie Sie sie beschreiben, sind selbst bei kommerziellen Projekten selten. Sie erfordern zusätzlichen Aufwand mit geringem Wert für die Entwickler. Außerdem neigen Entwickler dazu, keine Dokumentation zu schreiben, es sei denn, sie müssen dies wirklich tun. Einige Projekte haben das Glück, Mitglieder zu haben, die gut im technischen Schreiben sind und daher eine gute Benutzerdokumentation haben. Es ist unwahrscheinlich, dass die Entwicklerdokumentation, falls vorhanden, aktualisiert wird, 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 Standard-Code-Layouts. 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 davon haben, welche Art von Funktion fehlerhaft ist, ist es häufig möglich, schnell in der Verzeichnishierarchie zu navigieren.

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 der Funktionalität vorzunehmen.

Für Sprachen, die Scoping bieten, können Sie Methoden mit privatem Scoping umgestalten. In diesem Fall müssen Sie möglicherweise die Anrufer sowie die Refactor-Methode oder -Methoden ändern. Dies erfordert ein umfassenderes, 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 habe ein äußerst begrenztes Verständnis des Codes, der zum Generieren der Schnittstelle verwendet wird.

6
BillThor

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 hochkarätiger Open Source-Softwareprojekte enthält. Ich bin mir jedoch nicht sicher, ob es genau die Rolle erfüllt, die Sie sich vorstellen, da ich glaube, dass das Hauptpublikum Entwickler sein sollen, die nach Mustern suchen, denen sie beim Erstellen ihrer eigenen Anwendungen folgen können, und keine neuen Mitwirkenden an den im Buch vorgestellten Projekten (obwohl ich sicher bin, dass es dort hilfreich sein könnte).

5
bjmc

Weil es weit mehr Open-Source-Programmierer als Open-Source-Techniker gibt.

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

Eine gut dokumentierte Codebasis ist besser als eine weniger dokumentierte, aber die Dokumentation kann leicht so lange dauern, bis der Code überhaupt geschrieben wurde. Ihre Frage ist also, ist es besser, eine gut dokumentierte Codebasis oder eine doppelt so große Codebasis zu haben? Sind die Kosten, um die Dokumentation auf dem neuesten Stand zu halten, wenn Codeänderungen die Beiträge zusätzlicher Entwickler wert sind, die sie möglicherweise bringen oder nicht?

Versandcode gewinnt. Wenn Sie den Aufwand für andere Dinge als den Versandcode reduzieren, kann dies dazu führen, dass Code häufiger versendet wird und mit größerer Wahrscheinlichkeit versendet wird, bevor die Ressourcen ausgehen.

Dies bedeutet nicht, dass Dinge neben dem Versand wichtig sind. Die Dokumentation erhöht den Wert des Projekts, und bei einem ausreichend großen Projekt sind die Verbindungskosten für das Hinzufügen eines weiteren Entwicklers möglicherweise weitaus höher als für das Hinzufügen eines Dokumentators. Wie bereits erwähnt, kann die Dokumentation die Investitionen in das Projekt erhöhen (indem sie neuen Programmierern den Beitritt erleichtert).

Nichts verkauft sich jedoch so gut wie Erfolg: Ein Projekt, das nicht funktioniert oder etwas Interessantes tut, zieht auch Entwickler selten 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 Verbraucher Ihrer Codebasis wollen, und Ihre Codebasis wertvoll zu machen.

Manchmal macht es diejenigen, die die Aufgabe besser machen, schwieriger, die Dinge schwieriger zu machen. Entweder aufgrund eines höheren Engagements für das Projekt (stundenlanges Erlernen der Architektur) oder aufgrund von Fähigkeiten (wenn Sie bereits ein Experte für verwandte Technologien sind, ist es schneller, sich auf den neuesten Stand zu bringen, sodass die Barriere des Mangels besteht Eine solche Dokumentation ist weniger wichtig: Daher treten mehr Experten dem Team bei und weniger Anfänger.

Schließlich sind die derzeitigen Entwickler aus den oben genannten Gründen wahrscheinlich Experten für die Codebasis. Das Schreiben einer solchen Dokumentation hilft nicht ihnen verstehen die Codebasis sehr, da sie bereits über das Wissen verfügen, es hilft nur anderen Entwicklern. Ein Großteil der Open-Source-Entwicklung basiert auf dem "Kratzen eines Juckreizes", den der Entwickler mit dem Code hat: Mangel an Dokumentation, die bereits sagt, was der Entwickler weiß, juckt selten.

4
Yakk