Pourquoi n'y a-t-il pas des aperçus de code pour les projets open-source? [fermé]

Il existe des projets open source très complexes, et pour certains d'entre eux, je pense que je pourrais apporter certaines contributions et j'aimerais pouvoir le faire, mais la barrière à l'entrée est trop élevée pour une seule raison: pour modifier une ligne de code à la fois. grand projet, vous devez tout comprendre.

Vous n'avez pas besoin de lire tout le code (même si vous lisez, cela ne suffira pas) et de comprendre chaque ligne, et pourquoi, car le code est probablement modularisé et compartimenté, il y a donc des abstractions en place, mais Même dans ce cas, vous devez avoir une vue d' ensemble du projet afin de savoir où sont les modules, où un module s'interface avec un autre, que fait exactement chaque module et pourquoi , et dans quels répertoires et fichiers se trouvent chacun de ces événements.

J'appelle cette vue d'ensemble du code , comme le nom d'une section que les projets open source pourraient avoir sur le site Web ou dans la documentation expliquant leur code à des tiers. Je pense que cela aiderait les contributeurs potentiels , car ils seraient en mesure d'identifier les endroits où ils pourraient construire, les véritables codeurs principaux impliqués, tout en écrivant tout, en réorganisant leurs esprits, et en aidant les utilisateurs , comme ils le feraient. être utile pour comprendre et mieux signaler les bugs qu’ils rencontrent et peut-être même devenir contributeurs.

Mais je n'ai encore jamais vu un de ces "aperçus de code". Pourquoi? Y a-t-il des choses comme celles-ci et je les manque? Des choses qui font le même travail que je décris? Ou est-ce une idée complètement inutile, puisque tout le monde, sauf moi, peut facilement comprendre des projets comportant des milliers de lignes de code?

Parce que créer et maintenir un tel document demande un effort supplémentaire, et que trop de gens ne comprennent pas les avantages qui en découlent.

Beaucoup de programmeurs ne sont pas de bons rédacteurs techniques (bien que beaucoup le soient); ils écrivent rarement des documents strictement destinés à la consommation humaine, ils n'ont donc pas de pratique et n'aiment pas le faire. Écrire une vue d'ensemble du code prend du temps que vous ne pouvez pas dépenser pour le codage, et l' avantage initial d'un projet est toujours plus grand si vous pouvez dire "Nous prenons en charge les trois variantes de codage" plutôt que "Nous avons des explications très utiles sur notre code!" L'idée qu'un tel document attirera plus de développeurs, de sorte qu'à long terme, plus de code sera écrit, ne leur est pas étranger , mais il est perçu comme un pari incertain; Ce texte fera-t-il vraiment la différence entre accrocher ou non un collaborateur? Si je continue à coder en ce moment , obtenir cette chose faite.

Un document de synthèse de code peut également donner aux gens le sentiment d'être sur la défensive; il est difficile de décrire des décisions de niveau supérieur sans ressentir le besoin de les justifier, et très souvent, les personnes prennent des décisions sans raison qui «sonne assez bien» lorsqu'elles sont réellement écrites. Il existe également un effet lié à celui mentionné ci-dessus: dans la mesure où la mise à jour du texte pour l'adapter au code en cours de changement nécessite un effort supplémentaire, cela peut décourager les modifications radicales du code. Parfois, cette stabilité est une bonne chose, mais si le code nécessite vraiment une réécriture de niveau intermédiaire, il devient un handicap.

La vérité sèche et dure?

La documentation n'est pas faite car les projets peuvent s'en passer.

Même les projets open source font souvent face à une concurrence féroce. La plupart de ces projets ne commencent pas par de grandes épaules, ils sont une idée brillante, souvent une idée brillante pour un homme.

En tant que tels, ils ne peuvent pas se permettre le temps et les coûts liés à l'embauche de spécialistes en documentation, même s'ils ont offert de coopérer gratuitement. En fait, un projet documenté a généralement commencé par plusieurs itérations initiales. Cela commence souvent par 1 à 3, peut-être 5 personnes écrivent leur idée de roman et la montrent au monde entier comme preuve de concept. Si l'idée se révèle bonne, les "adeptes" peuvent éventuellement en ajouter, ils ont tendance à commencer à demander des extensions, de nouvelles options, des traductions ... À ce stade, le code reste un prototype, généralement avec des options et des messages codés en dur.

Tous les projets open source ne vont pas au-delà de cette phase, seuls ceux qui dépassent la "masse critique" doivent attirer l’intérêt du public. En outre, l'un des développeurs débutants doit "penser grand et loin" et planifier des extensions, etc. Il pourrait aussi bien devenir le projet "évangéliste" et parfois aussi "chef de projet" (parfois ce sont des personnes différentes). C'est une étape nécessaire pour mener à bien le projet, de la validation de principe à la réalité établie de l'industrie.

Même dans ce cas, le chef de projet peut choisir de ne pas créer de documentation.

Un projet dynamique et en croissance serait à la fois ralenti et la documentation serait vraiment en retard par rapport au code alors qu'elle était vraiment améliorée, pour mettre en œuvre des traductions, des options, des gestionnaires de plug-ins ...

Ce qui se passe habituellement est:

1. Un bref document d'introduction est établi sur le projet et son orientation (la "feuille de route").
2. Si possible, une API est développée et celle-ci est choisie comme "code documenté" sur la majeure partie du code sous-jacent.
3. En particulier, l'API mais aussi les autres codes sont reformatés et des commentaires spéciaux "PHPdoc" / "Javadoc" etc. sont ajoutés. Ils offrent un compromis décent entre temps passé et récompense: même un programmeur modeste sait généralement écrire une ligne décrivant ses fonctions, les paramètres étant "auto" également documentés, le tout lié à son code et évitant ainsi la documentation " désynchronisation "et retard de développement.
4. Le plus souvent, un forum est créé. C'est un puissant média social où les utilisateurs finaux et les programmeurs peuvent se parler (et entre leurs pairs, éventuellement dans les sous-forums "devs only"). Cela permet à beaucoup de connaissances d’émerger lentement et d’être consolidées par communauté (lisez: ne pesez pas sur l’équipe de développeurs) FAQ et HOWTO.
5. Dans les très gros projets, un wiki est également créé. J'énonce les "grands projets" car ce sont souvent ceux qui ont le plus d'abonnés pour créer un wiki (un dev le fait) et ensuite le remplir au-delà des "éléments de base" (la communauté le fait).

Les documents de synthèse tels que ceux que vous décrivez sont rares, même pour des projets commerciaux. Ils nécessitent un effort supplémentaire sans grande valeur pour les développeurs. De plus, les développeurs ont tendance à ne pas écrire de documentation à moins d'en avoir réellement besoin. Certains projets ont de la chance d'avoir des membres qui savent écrire et qui ont une bonne documentation utilisateur. La documentation destinée aux développeurs, si elle existe, ne sera probablement pas mise à jour pour refléter les modifications du code.

Tout projet bien organisé aura une arborescence de répertoires relativement explicite. Certains projets documenteront cette hiérarchie et / ou les raisons pour lesquelles elle a été choisie. De nombreux projets suivent des dispositions de code relativement standard. Par conséquent, si vous en comprenez un, vous comprendrez la présentation des autres projets utilisant la même disposition.

Pour modifier une ligne de code, vous devez avoir une compréhension limitée du code environnant. Vous ne devriez jamais avoir à comprendre la base de code entière pour le faire. Si vous avez une idée raisonnable du type de fonction cassée, il est souvent possible de naviguer assez rapidement dans la hiérarchie des répertoires.

Pour modifier une ligne de code, vous devez comprendre la méthode dans laquelle la ligne est trouvée. Si vous comprenez le comportement attendu de la méthode, vous devriez pouvoir apporter des modifications correctives ou des extensions à la fonctionnalité.

Pour les langues qui fournissent une portée, vous pouvez refactoriser les méthodes étendues privées. Dans ce cas, vous devrez peut-être modifier les appelants ainsi que la ou les méthodes de refactorisation. Cela nécessite une compréhension plus large, mais toujours limitée, de la base de code.

Voir mon article Ajout de SHA-2 à tinyca pour un exemple de la façon dont de tels changements peuvent être effectués. J'ai une compréhension extrêmement limitée du code utilisé pour générer l'interface.

Y a-t-il des choses comme celles-ci et je les manque? Des choses qui font le même travail que je décris?

Il existe un excellent livre intitulé The Architecture of Open Source Applications (L'architecture des applications open source) qui fournit des descriptions détaillées d'une variété de projets de logiciels open source de premier plan. Cependant, je ne sais pas si cela remplit exactement le rôle que vous imaginez, car je pense que son public cible est principalement destiné aux développeurs recherchant des modèles à suivre lors de la création de leurs propres applications, et non à de nouveaux contributeurs aux projets présentés dans le livre. (même si je suis sûr que cela pourrait être utile là-bas).

Parce qu'il y a beaucoup plus de programmeurs open source que de rédacteurs techniques open source.

La documentation nécessite de la maintenance et du temps pour se tenir à jour. Plus la documentation est volumineuse, plus elle en prend. Et une documentation qui n'est pas synchronisée avec le code est pire qu'inutile: elle induit en erreur et cache au lieu de révéler.

Une base de code bien documentée vaut mieux qu'une base moins documentée, mais la documentation peut facilement prendre aussi longtemps que l'écriture du code. Votre question est donc la suivante: est-il préférable d’avoir une base de code bien documentée ou une base de code deux fois plus volumineuse? Le coût de mise à jour de la documentation chaque fois que des modifications de code valent-elles les contributions de développeurs supplémentaires qu’il apporte ou non?

Le code d'expédition gagne. Réduire la quantité d'efforts investis dans des tâches autres que le code d'expédition peut faire en sorte que le code soit envoyé plus souvent et soit plus susceptible d'être envoyé avant qu'il ne manque de ressources.

Cela ne signifie pas que les choses en dehors de l'expédition importent. La documentation ajoute de la valeur au projet et, avec un projet suffisamment grand, le coût d'interconnexion lié à l'ajout d'un autre développeur peut être bien supérieur à celui de l'ajout d'un documenteur. Et, comme indiqué, la documentation peut augmenter les investissements dans le projet (en facilitant l'adhésion de nouveaux programmeurs).

Cependant, rien ne se vend comme le succès: un projet qui ne fonctionne pas ou ne fait rien d'intéressant attire rarement les développeurs.

La documentation d'une base de code est une forme de méta-travail. Vous pouvez passer beaucoup de temps à rédiger des documents sophistiqués décrivant une base de code peu utile, ou à créer des tâches que les utilisateurs de votre base de code veulent et leur donner valeur.

Parfois, rendre les choses plus difficiles rend ceux qui font la tâche mieux. Soit en raison d’un degré plus élevé d’engagement dans le projet (passer des heures à apprendre l’architecture), soit en raison du biais lié aux compétences (si vous êtes déjà un expert en technologie connexe, le progrès sera plus rapide, de sorte que la barrière du manque de la documentation est moins importante: ainsi plus d’experts rejoignent l’équipe et moins de débutants).

Enfin, pour les raisons susmentionnées, les développeurs actuels seront probablement des experts en code. Écrire une telle documentation ne les aide pas beaucoup à comprendre le code de base, car ils en ont déjà la connaissance, cela n’aide que les autres développeurs. Une grande partie du développement open source est basée sur le fait de "gratter une démangeaison" que le développeur a avec le code: le manque de documentation qui dit déjà ce que le développeur sait démange rarement.

En plus d’ être un effort supplémentaire , certains projets open source paralysent délibérément leurs documentations afin d’obtenir des emplois en freelance pour leurs responsables (pour mettre en œuvre quelque chose ou pour organiser des formations). Non seulement ils n'ont pas de vue d'ensemble du code, mais leur API et leurs tutoriels sont mauvais ou manquent beaucoup de choses.

Pour n'en nommer qu'un très populaire: bluez. Bonne chance pour trouver un bon tutoriel, autre que pour rechercher des périphériques à proximité.