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

60

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 sont les modules, 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?

fiatjaf
la source
7
Vous voulez dire un document de conception? J'ai vu le projet rare avec une description de chaque paquet, mais c'est déjà généralement une API.
Monstre à cliquet
14
Pourquoi? Parce que rares sont les projets dont les responsables souhaitent investir dans la rédaction et la maintenance de documents de haute qualité, et souvent, ils peuvent ne pas en comprendre les avantages.
Alex D
9
La documentation peut être obsolète ou inexacte par rapport au comportement réel. Le code ne peut pas. La plupart des projets préfèrent donc le code.
Paul Draper
5
En outre, il est facile de sous-estimer tout ce que vous pouvez apprendre sur un projet si vous réglez une minuterie de cuisine pendant environ 2 heures et Just Read It (tm).
Kos
43
Bienvenue dans le monde axé sur la communauté: si ce n'est pas fait, c'est parce que vous ne l'avez pas encore fait :)
mgarciaisaia

Réponses:

60

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.

Kilian Foth
la source
6
Eh bien, il semble que la réponse soit oui: gnunet.org/gnunet-source-overview
fiatjaf
5
Si vous le souhaitez, proposez-vous de l'écrire. L'intérêt des projets open source est que les gens peuvent et doivent apporter ce qu'ils peuvent, à condition que la communauté reconnaisse qu'il vaut la peine de l'intégrer.
Keshlam
8
@keshlam - cela a du sens si vous contribuez déjà au projet ... mais si vous êtes un contributeur potentiel qui tente d'obtenir une idée de base du fonctionnement du code, vous êtes la pire personne possible pour écrire ce document ....
Jon Story
13
@JonStory Votre argument est valable, mais dans la pratique, j'ai aussi constaté que le contraire était vrai parfois. Dans certains projets, j'ai fini par écrire une documentation basée sur les notes que j'avais prises lors de l'apprentissage d'une base de code non documentée. C'était une meilleure documentation car je devais commencer par l'API que je pouvais voir, puis creuser de plus en plus profondément. Les développeurs qui avaient écrit le code avaient déjà un modèle du code dans leur tête et avaient donc de nombreuses hypothèses sur ce que quelqu'un saurait déjà. La documentation par un nouvel utilisateur du projet peut constituer une meilleure documentation pour un nouvel utilisateur du projet.
Joshua Taylor
6
@JonStory: Si vous vous engagez dans un projet bien documenté, vous devrez commencer à comprendre cela de toute façon. Faire de vos notes une partie du projet permet d’économiser le travail d’une autre personne. (Je ne pense pas que quiconque se servirait de la présence ou de l'absence de documents comme facteur décisif pour décider de contribuer ou non). Améliorer simplement les commentaires javadoc (ou l'équivalent) peut être un moyen précieux de commencer à contribuer. Sérieusement, c'est le principe de base de l'open-source: si vous voyez quelque chose à faire, faites-le plutôt que d'attendre que quelqu'un d'autre le fasse.
Keshlam
14

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).
Dario Fumagalli
la source
2
SENSATIONNEL!! nous vivons (et travaillons) dans deux mondes totalement différents. Où que vous travailliez actuellement, sortez vite de là et trouvez une entreprise (il y en a beaucoup) où cela se fait correctement, car cela vous permet effectivement d'économiser de l'argent. Ne laissez jamais des directeurs / codeurs de cow-boy pointus vous dire le contraire.
Mawg
6
+1, je suis d'accord avec presque tous vos points, le seul énoncé que je rejette fermement est que les paramètres sont "auto" documentés . Lorsque nous pensons aux explications plutôt qu'aux simples contraintes de syntaxe / type, rien n'est "auto-documenté"; un commentaire généré dans le style Retourne le X. Pour une méthode getX , ce n'est pas une documentation utile, c'est juste un remplissage sans aucune information supplémentaire.
OU Mapper
3
@Mawg fournir une bonne documentation est un investissement, vous perdez du temps de développement en échange de (espérons-le) plus de contributeurs dans le futur et de quelques autres avantages. Mais comme beaucoup de projets de ce type, cela ne vaut que si vous savez qu'il y a de bonnes chances que le projet aboutisse et que la plupart des projets logiciels échouent. Il est important de prendre en compte le biais de survie lorsque vous déplorez le manque de documentation dans les projets réussis.
congusbongus
N'est-il pas possible que ces projets échouent parce qu'ils ne documentent pas? Et par document, je veux dire plan, pour que vous compreniez, plutôt que de vous asseoir devant le clavier et de vous en éloigner. Voici mon estimation pour le cycle de vie d'un projet, tous les chiffres +/- 5%. Contenu initial (exigences et cas d'utilisation, architecture, conception détaillée) 50%, codage de 10 à 15%, tests, le reste. "Si vous ne parvenez pas à planifier, vous planifiez d'échouer"
Mawg
6

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.

BillThor
la source
1
Le point important ici n'était pas d'affirmer tout ce que vous devez savoir sur le code pour effectuer un changement. Bien sûr, cela dépendra de beaucoup de choses, mais vous n’aurez jamais besoin de comprendre tout le code, aucun aperçu ne vous donnera cette compréhension, mais même pour trouver la ligne de code que vous allez modifier, vous avez besoin d’une certaine connaissance de la structure générale du projet.
fiatjaf
+1 Il n'y a rien de spécial à propos de l'open source. Au cours de mes plus de 10 ans d’expérience dans l’industrie, je n’ai jamais vu un document de synthèse. Ce qui se passe généralement, c’est que les employeurs s’attendent à ce que le premier mois d’emploi ait une productivité nulle parce que vous étudiez la base de code. Les "
vues d'
5

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

bjmc
la source
cela ressemble plus à un commentaire, voir Comment répondre
gnat
4
Je ne trouve pas votre commentaire constructif. Qu'est-ce qui vous manque en particulier? De nombreuses autres réponses ici sont de longues spéculations sur les raisons possibles pour lesquelles les développeurs pourraient ne pas écrire la documentation de présentation. J'ai lié à un exemple spécifique de bons documents de synthèse.
Bjmc
1
Je pense qu'il manque une réponse à la question posée: "Pourquoi n'y a-t-il pas des aperçus de code pour les projets open source?"
Gnat
3
Je dirais qu'il n'est pas possible de répondre avec précision à la question telle qu'elle est écrite alors qu'en réalité, il existe des aperçus de code pour certains projets open source. J'ai modifié ma réponse pour indiquer clairement que je ne répondais qu'à une demande d'exemples manqués par l'utilisateur.
Bjmc
1
La question telle qu'elle est écrite demande "Y at-il des choses comme celles-ci et je les manque?" Cette réponse répond définitivement, en pointant vers une collection existante de tels aperçus de code. En tant que tel, je pense que c'est une excellente (et appropriée) réponse à la question.
Jim Garrison
4

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.

Yakk
la source
+1 "La documentation peut facilement prendre aussi longtemps que l'écriture du code" - ou plus longtemps!
Marco
-1

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

BЈовић
la source
8
Peu importe le nombre d’exemples que vous pouvez citer pour des projets open source mal documentés, à mon avis, l’affirmation selon laquelle "ils paralysent délibérément leurs documentations" doit être étayée par des preuves concluantes (et même dans ces cas-là, cela n’a probablement déclaration générale).
OU Mapper
@ORMapper Commençons par "Bluez - le plus grand mystère de Linux" . En tant que seule bibliothèque bluetooth pour Linux, j'ai du mal à croire que ce n’est pas de la documentation car c’est un effort supplémentaire. Enfer, il y a doxygen, et comment est-il difficile d'écrire des tutoriels simples?
BЈовић
@ORMapper Ensuite, il y a le noyau Linux. S'il vous manque quelque chose (comme un pilote de noyau), si votre entreprise manque de compétences, vous pouvez engager quelqu'un, ou trouver un pigiste ou une entreprise qui le fera pour vous. Donc, il est open source, mais il vient avec un prix
BЈовић
@ORMapper Ensuite, il y a un projet open source, avec une documentation au format papier. Donc, vous achetez un livre, et il n'y a pas d'autre documentation. Cette documentation est-elle invalidante ou non?
BЈовић
2
Pour ce que ça vaut, j'ai vu suffisamment de profit sur une documentation de mauvaise qualité pour au moins me demander si c'est intentionnel. Lorsque les mêmes groupes mettant en ligne une documentation à moitié optimisée sont plus qu'heureux de vous vendre un livre ou un cours de formation, il ne faut pas beaucoup de cynisme pour parvenir à cette conclusion.
cHao