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

60

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?

Fiatjaf
quelle
7
Sie meinen ein Designdokument? Ich habe das seltene Projekt mit einer Beschreibung jedes Pakets gesehen, aber das ist normalerweise bereits eine API.
Ratschenfreak
14
Warum? Da es nur wenige Projekte gibt, deren Projektbetreuer die Mühe aufwenden möchten, hochwertige Dokumentationen zu schreiben und zu pflegen, verstehen sie die Vorteile möglicherweise auch nicht.
Alex D
9
Die Dokumentation kann veraltet oder in Bezug auf das tatsächliche Verhalten ungenau sein. Code kann nicht. Daher bevorzugen die meisten Projekte Code.
Paul Draper
5
Es ist auch leicht zu unterschätzen, wie viel Sie über ein Projekt lernen können, wenn Sie einen Küchentimer für ungefähr 2 Stunden einstellen und Just Read It (tm).
Kos
43
Willkommen in der von der Community geprägten Welt: Wenn es nicht getan wird, liegt das daran, dass Sie es nicht getan haben :)
mgarciaisaia

Antworten:

60

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.

Kilian Foth
quelle
6
Nun, die Antwort scheint ja zu sein: gnunet.org/gnunet-source-overview
fiatjaf
5
Wenn du willst, dass es existiert, melde dich freiwillig, um es zu schreiben. Der springende Punkt bei Open-Source-Projekten ist, dass die Menschen beitragen können und sollten, was sie können, vorausgesetzt, die Community stimmt zu, dass es sich lohnt, sie zu integrieren.
Keshlam
8
@keshlam - das macht Sinn, wenn Sie bereits einen Beitrag zum Projekt geleistet haben ... aber wenn Sie ein potenzieller Beitrag leisten, der versucht, eine grundlegende Vorstellung davon zu bekommen, wie der Code funktioniert, sind Sie die schlechteste Person, die es zu schreiben gibt das Dokument ....
Jon Story
13
@ JonStory Ihr Punkt ist gut, aber in der Praxis habe ich manchmal auch das Gegenteil festgestellt. In einigen Projekten habe ich eine Reihe von Dokumentationen geschrieben, die auf Notizen basieren, die ich während des Lernens einer undokumentierten Codebasis erstellt habe. Es war eine bessere Dokumentation, weil ich an der API anfangen musste, die ich sehen und dann tiefer und tiefer graben konnte. Die Entwickler, die den Code geschrieben hatten, hatten bereits ein Modell des Codes in ihren Köpfen und so hatten sie viele Annahmen darüber, was jemand bereits wissen würde. Die Dokumentation durch eine neue Person im Projekt kann eine bessere Dokumentation für eine neue Person im Projekt sein.
Joshua Taylor
6
@JonStory: Wenn Sie in ein weniger als perfekt dokumentiertes Projekt involviert sind, müssen Sie trotzdem anfangen, dies herauszufinden. Wenn Sie Ihre Notizen in das Projekt einbinden, können Sie der nächsten Person die Arbeit ersparen. (Ich weiß nicht, ob irgendjemand das Vorhandensein oder Fehlen von Dokumenten als Entscheidungsfaktor für einen Beitrag heranziehen würde.) Eine einfache Verbesserung der Javadoc-Kommentare (oder einer gleichwertigen Methode) kann eine wertvolle Möglichkeit sein, einen Beitrag zu leisten. Im Ernst, das ist das Grundprinzip von Open Source: Wenn Sie etwas sehen, das getan werden muss, tun Sie es, anstatt darauf zu warten, dass jemand anderes es tut.
Keshlam
14

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).
Dario Fumagalli
quelle
2
BEEINDRUCKEND!! wir leben (und arbeiten) in zwei völlig unterschiedlichen welten. Wo immer Sie gerade arbeiten, gehen Sie schnell von dort weg und finden Sie ein Unternehmen (es gibt viele), in dem alles richtig gemacht wird, denn das spart Ihnen tatsächlich Geld. Lassen Sie sich von spitzen Managern / Cowboy-Programmierern niemals etwas anderes sagen.
Mawg
6
+1, ich stimme fast allen Ihren Punkten zu. Die einzige Aussage, die ich nachdrücklich ablehne, ist, dass Parameter "automatisch" dokumentiert werden . Wenn wir eher an Erklärungen als an die bloßen Syntax- / Typbeschränkungen denken, wird nichts "automatisch dokumentiert"; Ein generierter Kommentar im Stil Gibt das X zurück. Eine getX- Methode ist keine hilfreiche Dokumentation, sondern nur eine Füllung ohne zusätzliche Informationen.
ODER Mapper
3
@Mawg eine gute Dokumentation bereitzustellen ist eine Investition, Sie verzichten auf Entwicklerzeit als Gegenleistung für (hoffentlich) mehr Mitwirkende in der Zukunft und einige andere Vorteile. Aber wie bei vielen seiner Art lohnt es sich nur, wenn Sie wissen, dass die Chancen gut stehen und die meisten Softwareprojekte scheitern. Es ist wichtig, sich der Vorurteile gegenüber Überlebenden bewusst zu sein, wenn Sie den Mangel an Dokumentation in erfolgreichen Projekten beklagen.
Congusbongus
Ist es nicht möglich, dass diese Projekte scheitern, weil sie nicht dokumentiert sind? Und mit Dokument meine ich Planen, damit du verstehst, anstatt dich an die Tastatur zu setzen und weg zu hämmern. Hier ist meine Schätzung für einen Projektlebenszyklus, alle Zahlen +/- 5%. Erste Schritte (Anforderungen und Anwendungsfälle, Architektur, detailliertes Design): 50%, Kodierung: 10 bis 15%, Test, der Rest. "Wenn Sie nicht planen, planen Sie nicht"
Mawg
6

Ü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.

BillThor
quelle
1
Der wichtige Punkt hier war nicht, zu behaupten, wie viel Sie über den Code wissen müssen, um eine Änderung vorzunehmen. Natürlich hängt dies von vielen Dingen ab, aber Sie müssen nie den gesamten Code verstehen, weder eine Übersicht wird Ihnen dieses Verständnis vermitteln, noch benötigen Sie bestimmte Kenntnisse , um die Codezeile zu finden, die Sie ändern werden die allgemeine Projektstruktur.
Fiatjaf
+1 Open Source ist nichts Besonderes. In meiner über 10-jährigen Erfahrung in der Industrie habe ich noch nie ein Übersichtsdokument gesehen. In der Regel erwarten Arbeitgeber, dass der erste Monat Ihrer Beschäftigung keine Produktivität aufweist, da Sie die Codebasis studieren. "Übersichten" werden normalerweise als Fragen an Ihre Mitarbeiter implementiert
slebetman
5

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).

bjmc
quelle
Dies liest sich eher wie ein Kommentar, siehe Wie man antwortet
Mücke
4
Ich finde Ihren Kommentar nicht konstruktiv. Was fehlt Ihnen konkret? Viele der anderen Antworten hier sind langwierige Spekulationen über mögliche Gründe, warum Entwickler möglicherweise keine Übersichtsdokumentation schreiben. Ich habe ein bestimmtes Beispiel für gute Übersichtsdokumente verlinkt.
Bjmc
1
Ich habe das Gefühl, dass eine Antwort auf die gestellte Frage fehlt: "Warum gibt es keine Codeübersichten für Open-Source-Projekte?"
gnat
3
Ich würde behaupten , es nicht möglich ist , genau wie geschrieben auf die Frage zu antworten , wenn in der Tat, es gibt Code - Übersichten für einige Open-Source - Projekte. Ich habe meine Antwort bearbeitet, um zu verdeutlichen, dass ich knapp auf eine Anfrage nach Beispielen reagiere, die der Benutzer möglicherweise verpasst hat.
Bjmc
1
Die schriftliche Frage lautet: "Gibt es solche Dinge und ich vermisse sie?" Diese Antwort reagiert definitiv und verweist auf eine vorhandene Sammlung solcher Codeübersichten. Als solches finde ich es eine großartige (und angemessene) Antwort auf die Frage.
Jim Garrison
4

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.

Yakk
quelle
+1 "Dokumentation kann leicht so lange dauern wie das Schreiben des Codes an erster Stelle" - oder länger!
Marco
-1

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.

BЈовић
quelle
8
Egal wie viele Beispiele Sie für schlecht dokumentierte Open Source - Projekte auflisten können, meiner Meinung nach muss die Behauptung, dass sie "ihre Dokumentationen absichtlich lähmen", durch schlüssige Beweise gestützt werden (und selbst dann gilt dies wahrscheinlich nicht als eine Allgemeine Äußerung).
ODER Mapper
@ORMapper Beginnen wir mit "Bluez - Greatest Linux Mystery" . Als einzige Bluetooth-Bibliothek für Linux fällt es mir schwer zu glauben, dass dies keine Dokumentation ist, da es ein zusätzlicher Aufwand ist. Verdammt, es gibt Sauerstoff und wie schwer ist es, einfache Tutorials zu schreiben?
B 2овић
@ORMapper Dann gibt es Linux-Kernel. Wenn Sie etwas vermissen (wie einen Kerneltreiber), wenn Ihrem Unternehmen das Fachwissen fehlt, können Sie entweder jemanden einstellen oder einen Freiberufler oder eine Firma finden, die dies für Sie erledigt. Also, es ist Open Source, aber es kommt mit einem Preis
BЈовић
@ORMapper Dann gibt es Open Source-Projekte mit Dokumentation in Papierform. Sie kaufen also ein Buch und es werden keine weiteren Unterlagen gegeben. Verkrüppelt diese Dokumentation oder nicht?
BЈовић
2
Für das, was es wert ist, habe ich genug Profit aus minderwertiger Dokumentation gesehen, um mich zumindest zu fragen, ob es beabsichtigt ist. Wenn die gleichen Gruppen, die halbherzige Dokumentationen online stellen, Ihnen gerne ein Buch oder einen Schulungskurs verkaufen, braucht es nicht viel Zynismus, um zu dieser Schlussfolgerung zu gelangen.
CHAO