Comment réussir des projets open source sans documentation sur leur conception ou leur architecture?

11

Je veux améliorer mes compétences en programmation en étudiant des projets open source célèbres, mais je trouve qu'il est facile de se perdre en sautant simplement dans leur code source.

J'ai donc décidé de lire leur documentation sur leur conception ou leur architecture (comme les diagrammes UML) pour avoir une idée générale de l'organisation de leur code en premier. À ma grande surprise, cependant, je ne trouve aucune documentation architecturale pour les grands projets open source tels que Hibernate, Spring, ASP.NET MVC, Rails, etc.

J'ai donc commencé à me demander: comment un projet open source peut-il réussir si les développeurs débutants n'ont pas de documentation architecturale / de conception à lire, ou si le chef de projet vient d'ouvrir le code source mais ferme sa documentation?

TomCaps
la source
3
"plus"? Pouvez-vous étayer cela avec des statistiques concrètes? Combien en avez-vous lu? Combien y en a-t-il? Combien manquaient de documentation appropriée? Si vous n'avez pas de chiffres, veuillez supprimer les mots comme «la plupart» et les remplacer par des faits réels basés sur ce que vous avez vraiment trouvé. Veuillez également mettre en majuscule «I» lorsque vous vous référez à vous-même.
S.Lott
@ S.Lott Désolé pour le "plus" subjectif. Je suis un débutant dans l'industrie du logiciel. J'essaie de rechercher des documents dont j'avais entendu parler pendant les études universitaires (tels que diagramme UML, organigramme, document de conception bref, document de conception détaillé, etc.) pour les projets mentionnés, à la fois sur le site Web de leur projet ou dans le référentiel de code, mais sans chance, seulement pour trouver un document de guide d'utilisation. Pouvez-vous s'il vous plaît m'apprendre un moyen courant de rechercher leurs documents de conception / d'architecture?
TomCaps
1
Veuillez supprimer "Many". C'est tout aussi incorrect que la plupart. veuillez mettre à jour la question pour répertorier spécifiquement les projets open source spécifiques qui manquent spécifiquement de la documentation spécifique que vous souhaitez voir. Soyez précis et précis. Veuillez ne pas être subjectif et vague.
S.Lott
Je soupçonne que la raison pour laquelle ASP.NET MVC n'inclut pas de diagrammes UML est que Visual Studio peut les créer à partir du code source.
user16764
5
Vous opérez sous la fausse supposition que "l'entreprenariat" est une bonne chose. Ce que vous avez appris au collège à propos du design, ce sont tous des mensonges: UML n'a absolument aucune valeur. Lors de la création d'un projet, tout ce dont vous avez besoin est une idée générale de ce qu'il doit faire et une volonté de le jeter si vous le faites mal la première fois. Pour un projet existant, il suffit généralement de parcourir l'en-tête principal pour avoir une bonne idée de la disposition du projet.
o11c

Réponses:

10

pourquoi un projet open source peut réussir si le développeur nouveau venu n'a pas de document d'architecture / design à lire?

L'hypothèse est invariablement faite que vous savez ce que vous faites et que vous avez une compréhension raisonnablement intime de ce que vous allez (et vous attendez) à voir.

Si vous examinez le code PHP du framework Symfony, par exemple, vous êtes censé déjà connaître l'injection de dépendances, les événements, le modèle / vue / modèle de contrôleur, etc.

De même, si vous plongez dans le code C du noyau linux, l'hypothèse est que vous serez réellement compétent en matière de modularité, de signaux, de processus, de threads, etc. On s'attend également à ce que vous ayez le don de manger de l'hexadécimal toute la journée et de creuser à travers des décharges avec une pelle géante.

Les mainteneurs ne se donneront pas la peine de documenter l'architecture parce que ce sont des choses factuelles. À l'occasion, vous trouverez un aperçu de ce qui se trouve dans l'arborescence source. Plus généralement cependant, la façon dont l'arborescence source est organisée rend les choses explicites.

En bref, si vous n'avez aucune des compétences que les responsables s'attendront à ce que vous connaissiez au moment où vous jetez un coup d'œil dans leur code, vous fouillez probablement des choses qui sont largement au-dessus de votre niveau de rémunération. Familiarisez-vous d'abord avec les concepts - Qu'est-ce que le modèle MVC? Qu'est-ce que l'injection de dépendance? Etc. Plongez ensuite.

Denis de Bernardy
la source
1
Cependant, si vous regardez les listes de diffusion, le noyau Linux a une discussion approfondie sur l'architecture chaque fois que quelqu'un a un problème ou souhaite changer quelque chose. Il y a aussi pas mal de documents écrits à ce sujet - mais pas dans l'arbre source du noyau lui-même.
edA-qa mort-ora-y
17

La plupart des projets open source réussis sont devenus réussis parce que, avant tout, le programme était impressionnant ou faisait quelque chose qu'aucun autre programme ne pouvait faire à l'époque. Cela ne signifie pas nécessairement que la source est bien documentée, car les programmeurs qui ont commencé le projet au départ connaissent suffisamment le code pour ne pas en avoir besoin. C'est une triste réalité que les projets open source n'aient pas besoin d'être bien documentés. Il doit s'agir d'un bon programme ou d'un programme médiocre mais bien documenté pour que les programmeurs s'y intéressent.

Neil
la source
Dans mon entreprise, les développeurs doivent fournir un document de conception détaillée avant d'être approuvé, écrire un code sur un projet. Cette procédure est-elle anormale pour un projet open source?
TomCaps
5
@TomCaps Je pense que la principale raison pour laquelle si peu de projets FOSS ont une documentation complète est assez simple: si vous écrivez un petit programme pour résoudre un besoin que vous avez, il est probable que depuis votre développeur que vous n'avez pas besoin de documentation, vous vont vouloir passer votre temps à améliorer le programme plutôt que d'écrire de la documentation qui n'est même pas garantie d'être utile à quiconque (et si le projet n'est jamais utilisé par personne sauf le développeur?). Ce n'est pas la meilleure pratique, mais de nombreux projets FOSS manquent de temps pour les développeurs.
Jeff Welling
5
@TomCaps: Cette procédure est anormale pour la plupart des entreprises que je connais ...
Treb
1
La plupart des projets open source ne sont pas des entreprises. Vous pensez à ce qui se passe quand il y a un projet que je suis payé pour construire, avec un délai et un budget. Si vous avez un tas de gens qui codent pour combler un besoin qu'ils ont ou pour le plaisir et qu'il n'y a pas de budget ou de client, vous n'avez pas ce genre de choses.
Elin
1
@TomCaps - quiconque écrit un logiciel Open Source peut faire exactement ce qu'il veut. Certains projets (par exemple la famille Apache) ont des règles et des lignes directrices pour toute personne qui commet du code et parfois cela inclut des normes de fragmentation, etc. mon expérience personnelle) est généralement sous-optimale. Une description détaillée de ce que le programme est censé faire laisse au développeur la liberté d'optimiser la mise en œuvre et d'appliquer des stratégies créatives à la solution.
James Anderson
12

Parce que les développeurs open source sont généralement talentueux et choisissent également des projets dans leur domaine d'expertise, ils ont déjà une "documentation" dans leur crâne. Avec peu d'exagération, une documentation approfondie n'est nécessaire que si vous en manquez: o)

Pour être honnête, je ne lis pas vraiment la "documentation" face à une base de code inconnue. Une introduction rapide, peut-être quelques croquis conceptuels et directement dans le code! Expérimentez, essayez de petits changements. Fonctionne parfaitement pour un code bien conçu. Si je suis confronté à un horrible gâchis, la meilleure façon de les apprendre est de les refondre petit à petit pour améliorer la clarté (idéalement à l'aide de tests unitaires).

Une autre raison pourrait être la simple conception organique de ces projets. L'architecture est alors une vision plutôt évoluée dans l'esprit des développeurs qu'une entité déclarée «documentée».

Mar
la source
8

La raison pour laquelle ces documents n'existent souvent pas est assez simple: les programmeurs aiment programmer, pas écrire de la documentation. Surtout avec les projets open source, auxquels les développeurs contribuent souvent pendant leur temps libre / de loisirs.

Fondamentalement, écrire de la documentation n'est pas amusant. Et s'ils ne sont pas payés pour cela, qui veut passer leur temps libre à faire quelque chose qui n'est pas amusant?

GrandmasterB
la source
Certains grands projets open source (GCC, le noyau Linux, Firefox, Qt, ....) ont la plupart (ou une partie importante) de leurs contributeurs payés pour travailler (à temps plein ou à mi-temps) sur le projet. Donc, même lorsqu'ils sont payés pour un logiciel gratuit, ils n'écrivent pas beaucoup de documentation
Basile Starynkevitch