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

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?

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.

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.

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

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?