Pourquoi n'y a-t-il pas des aperçus de code pour les projets open source?
Il existe des projets open source très complexes, et pour certains d'entre eux, je pense que je pourrais apporter quelques contributions, et j'aimerais pouvoir, mais la barrière à l'entrée est trop élevée pour une seule raison: pour changer une ligne de code à un grand projet, il faut tout comprendre.
Vous n'avez pas besoin de lire tout le code (même si vous lisez, ce ne sera pas suffisant) et de comprendre toutes les lignes et pourquoi, parce que le code est probablement modularisé et compartimenté, donc il y a des abstractions en place, mais même dans ce cas, vous devez obtenir un aperçu du projet afin de savoir où sont les modules, où fait l'interface d'un module avec l'autre, quoi exactement chaque module fait et pourquoi , et dans quels répertoires et fichiers se produisent chacune de ces choses.
J'appelle cela aperçu du code, comme le nom d'une section que les projets open source pourraient avoir dans le site Web ou la documentation expliquant leur code aux étrangers. Je pense que cela bénéficierait des contributeurs potentiels , car ils seraient en mesure d'identifier les endroits où ils pourraient construire, le réel les codeurs principaux impliqués, car ils seraient en mesure, tout en écrivant, de réorganiser leur esprit et aideraient les utilisateurs , car ils aideraient à comprendre et à mieux signaler les bogues qu'ils rencontrent et pourraient même devenir des contributeurs.
Mais je n'ai encore jamais vu l'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, car tout le monde, sauf moi, peut facilement comprendre des projets avec des milliers de lignes de code?
Parce que c'est un effort supplémentaire pour créer et maintenir un tel document, et trop de gens ne comprennent pas les avantages associés.
De nombreux programmeurs ne sont pas de bons rédacteurs techniques (bien que beaucoup le soient); ils écrivent rarement des documents strictement pour la consommation humaine, donc ils n'ont pas de pratique et n'aiment pas le faire. L'écriture d'une vue d'ensemble du code prend du temps que vous ne pouvez pas consacrer au codage, et l'avantage initial pour un projet est toujours plus important si vous pouvez dire "Nous prenons en charge les trois variantes d'encodage" plutôt que "Nous avons vraiment explications soignées de notre code! " L'idée qu'un tel document attirera plus de développeurs pour qu'à long terme plus de code soit écrit n'est pas exactement étrangère pour eux, 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, nous allons certainement faire ce truc.
Un document de présentation du code peut également donner aux gens un sentiment de défense; 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 gens prennent des décisions sans raison qui "semble assez bonne" lorsqu'elles sont écrites. Il y a aussi un effet lié à celui-ci: étant donné que la mise à jour du texte pour l'adapter au changement de code entraîne des efforts supplémentaires, cela peut décourager les modifications radicales du code. Parfois, cette stabilité est une bonne chose, mais si le code a vraiment besoin d'une réécriture de niveau intermédiaire, cela 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 sont souvent confrontés à une forte concurrence. La plupart de ces projets ne commencent pas avec de grandes épaules, ils démarrent une idée lumineuse, souvent une idée lumineuse d'un seul homme.
En tant que tels, ils ne peuvent pas se permettre le temps et les coûts d'embauche de documentaires humains, même s'ils ont offert de coopérer gratuitement. Un projet documenté, en fait, a généralement d'abord suivi plusieurs itérations. Cela commence souvent par 1-3, peut-être 5 gars écrivant leur idée de roman et la montrant au monde comme une preuve de concept. Si l'idée s'avère bonne, alors les "followers" peuvent ajouter, ils ont tendance à commencer à demander des extensions, de nouvelles options, des traductions… À ce stade, le code est encore un prototype, généralement avec des options et des messages codés en dur.
Tous les projets open source ne dépassent pas cette phase, seuls ceux qui brisent la "masse critique" nécessaire pour attirer l'intérêt du public. De plus, l'un des développeurs débutants doit "penser grand et loin" et planifier des extensions et ainsi de suite. Il pourrait tout aussi bien devenir "l'évangéliste" du projet et parfois aussi le "chef de projet" (d'autres fois ce sont des personnes différentes). C'est une étape nécessaire pour faire avancer le projet, de la preuve de concept à une réalité établie par l'industrie.
Même alors, 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 sur le code alors qu'il est en train d'être amélioré très dur, pour implémenter des traductions, des options, des plug-ins de gestionnaires ...
Ce qui se passe généralement, c'est:
- Un bref document d'introduction est fait, sur ce qu'est le projet et où il va (la fameuse "feuille de route").
- Si possible, une API est développée et celle-ci est choisie comme "code documenté" sur la majeure partie du code sous-jacent.
- Surtout 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 le temps passé et la récompense: même un programmeur modeste sait généralement écrire une seule ligne décrivant ses fonctions, les paramètres sont également "auto" documentés et le tout est lié à son code et ainsi ils évitent la documentation " désynchronisation "et retard de développement.
- Le plus souvent, un forum est créé. C'est un puissant réseau social où les utilisateurs finaux et les programmeurs peuvent se parler (et entre leurs pairs, peut-être dans des sous-forums "devs only"). Cela permet à beaucoup de connaissances d'émerger lentement et d'être consolidées par la communauté (lire: ne pas peser sur l'équipe de développeurs) FAQ et HOWTO.
- Dans les très gros projets, un wiki est également produit. J'énonce des "grands projets" parce que ce sont souvent ceux qui ont suffisamment de followers pour créer un wiki (un développeur le fait) et ensuite le remplir au-delà des "os nus" (la communauté le fait).
Les documents de synthèse tels que ceux que vous décrivez sont rares, même sur des projets commerciaux. Ils nécessitent un effort supplémentaire avec peu de valeur pour les développeurs. De plus, les développeurs ont tendance à ne pas écrire de documentation sauf s'ils en ont vraiment besoin. Certains projets ont la chance d'avoir des membres qui sont bons en rédaction technique et, par conséquent, ont une bonne documentation utilisateur. La documentation du développeur, 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 qui s'explique assez facilement. 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, donc si vous en comprenez un, vous comprendrez la disposition d'autres projets utilisant la même disposition.
Pour modifier une ligne de code, vous avez besoin d'une compréhension limitée du code environnant. Vous ne devriez jamais avoir à comprendre toute la base de code pour le faire. Si vous avez une idée raisonnable du type de fonction interrompue, 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 la portée, vous pouvez refactoriser les méthodes de portée privées. Dans ce cas, vous devrez peut-être changer 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 qui fournit des descriptions détaillées d'une variété de projets logiciels open source de haut niveau. Cependant, je ne sais pas si cela remplit exactement le rôle que vous imaginez, car je pense que son public principal est destiné aux développeurs à la recherche de 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).
Parce qu'il y a beaucoup plus de programmeurs open-source que de rédacteurs techniques open-source.
La documentation demande de la maintenance et du temps pour se tenir à jour. Plus la documentation est volumineuse, plus il en faut. Et la documentation qui n'est pas synchronisée avec le code est pire qu'inutile: elle induit en erreur et se 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 en premier lieu. 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 grande? Est-ce que le coût de la mise à jour de la documentation chaque fois que des modifications de code valent la contribution de développeurs supplémentaires peut ou non être apporté?
Le code d'expédition gagne. Réduire la quantité d'efforts consacrés à d'autres choses que le code d'expédition peut rendre le code expédié plus souvent et être plus susceptible d'être expédié avant qu'il ne soit à court de ressources.
Cela ne signifie pas que les choses à côté de l'expédition importent. La documentation ajoute de la valeur au projet et avec un projet suffisamment grand, le coût d'interconnexion de l'ajout d'un autre développeur peut être bien plus élevé que l'ajout d'un documentateur. Et, comme indiqué, la documentation peut augmenter l'investissement dans le projet (en facilitant l'adhésion de nouveaux programmeurs).
Cependant, rien ne se vend comme un succès: un projet qui ne fonctionne pas ou ne fait rien d'intéressant attire rarement les développeurs non plus.
La documentation d'une base de code est une forme de méta-travail. Vous pouvez passer beaucoup de temps à rédiger des documents fantaisistes décrivant une base de code qui n'a pas beaucoup de valeur, ou vous pouvez passer du temps à faire des choses que les consommateurs de votre base de code veulent et à donner à votre base de code une valeur.
Parfois, rendre les choses plus difficiles rend ceux qui accomplissent mieux la tâche. Soit en raison d'un degré plus élevé d'engagement envers le projet (passer des heures et des heures à apprendre l'architecture), soit en raison d'un biais de compétences (si vous êtes déjà un expert en technologie connexe, la mise à niveau sera plus rapide, donc la barrière du manque d'une telle documentation est moins importante: ainsi plus d'experts rejoignent l'équipe, et moins de débutants).
Enfin, pour les raisons mentionnées ci-dessus, les développeurs actuels sont susceptibles d'être des experts de la base de code. Écrire une telle documentation n'aide pas eux à bien comprendre la base de code, car ils ont déjà les connaissances, cela n'aide que les autres développeurs. Une grande partie du développement open source est basée sur "gratter une démangeaison" que le développeur a avec le code: manque de documentation qui dit déjà ce que le développeur sait qu'il démange rarement.