Pourquoi tant de bibliothèques n'ont-elles pas / peu de documentation? [fermé]

Dans la même veine que Comment les projets open source peuvent-ils réussir sans documentation sur leur conception ou leur architecture? question, je suis curieux: pourquoi tant de bibliothèques manquent-elles autant de documentation pour l'utilisateur final?

Mon point de vue est le suivant:

1. La plupart des gens conviennent que la lecture du code source est plus difficile que l'écriture du code source.
2. Sans documentation, il faut lire le code source de la bibliothèque pour pouvoir utiliser cette bibliothèque.
3. Par conséquent, l'utilisation de la bibliothèque non documentée représente plus de travail que la simple recréation de la bibliothèque à partir de zéro.
4. Par conséquent, si vous voulez que les gens utilisent votre bibliothèque, vous feriez mieux de vous assurer qu'elle est documentée.

Je sais que de nombreux développeurs n'aiment pas écrire de documents, et je conviens que cela peut être un travail fastidieux. Mais c'est un travail essentiel. Je dirais même qu'il est plus important qu'une bibliothèque ait une bonne documentation que la meilleure interface de programmation au monde. (Les gens utilisent des bibliothèques de merde tout le temps; peu utilisent des bibliothèques non documentées)

Oh, notez que lorsque je parle de documentation, je parle de vraie documentation. Pas Sandcastle / Javadoc / Doxygen passe-partout.

Je pense que vous avez surtout répondu à votre propre question: parce que dans la plupart des cas, les développeurs ne s'en soucieront pas. Le problème est particulièrement répandu dans les projets de volontariat.

Je pense cependant qu'il y a un autre problème majeur: dans de nombreux cas, les développeurs n'ont pas vraiment développé un modèle global de fonctionnement de leur bibliothèque (ou ont simplement du mal à articuler clairement ce modèle). Malheureusement, articuler ce modèle et la façon dont les éléments du logiciel s'emboîtent est souvent la partie la plus importante de la documentation.

Dans un cas typique, ce qui est écrit a une vue d'ensemble de très haut niveau ("C'est une bibliothèque pour faire des trucs sympas!") Puis une description de très bas niveau (type et description de chaque paramètre à transmettre à chaque fonction). Malheureusement, il y a rarement un niveau intermédiaire sur la théorie générale de la façon dont les choses sont censées fonctionner, comment les pièces s'emboîtent, etc. Cela tient en grande partie au fait que les développeurs n'ont souvent pas tenté de former, de rationaliser ou de comprendre code à ce niveau de détail particulier. Au moins dans certains cas que j'ai vus, les développeurs à qui on a demandé d'écrire de la documentation à ce niveau l'ont trouvé assez problématique - au point que beaucoup voulaient réécrire le code pour qu'il soit plus organisé et plus facile à expliquer à ce niveau de détail.

Bien écrire à ce niveau d'abstraction est souvent difficile - et si le développeur n'y a pas vraiment pensé à ce niveau d'abstraction, il trouvera souvent le code quelque peu embarrassant, et voudra peut-être le réécrire avant d'être satisfait de le libérer du tout.

Je pense que c'est parfois parce que le développeur est tellement enveloppé dans le code qu'il est "évident" pour lui / elle comment cela fonctionne et ils ne peuvent pas voir pourquoi cela ne serait pas évident pour quelqu'un d'autre. De même, de nombreux sites Web de produits disent à quel point leur produit est merveilleux, mais ne vous dit pas vraiment ce qu'il fait!

Vous avez vous-même souligné la réponse:

Je sais que de nombreux développeurs n'aiment pas écrire de documents, et je conviens que cela peut être un travail fastidieux.

En tant que programmeurs, nous aimons écrire du code, mais très peu d'entre nous aiment aussi écrire de la documentation.

Alors que tout bon codeur connaît la valeur d'une bonne documentation, il faut également beaucoup de temps pour le faire correctement. Comme ce n'est pas agréable et prend beaucoup de temps, il est mis dans la pile "à faire plus tard", donc il n'est jamais fait à un niveau satisfaisant.

En remarque, il est également très difficile pour un programmeur d'écrire de la documentation sur son propre produit. Comme ils connaissent si bien le système, certaines choses leur paraissent évidentes. Ces pièces ne sont souvent jamais mentionnées bien qu'elles ne soient pas évidentes pour le consommateur.

La rédaction de documentation est une compétence. Comme toutes les compétences, il faut de la pratique. Le temps et les efforts que nous consacrons à l'écriture de code sont immédiatement payants. Nous pouvons voir la nouvelle fonctionnalité, le bug corrigé, la vitesse améliorée. La rédaction de la documentation a un gain différé. Cela aide à long terme car de nouvelles personnes ont besoin de travailler sur le code ou si nous revenons travailler sur le code des mois ou des années plus tard. Il est naturel que nous nous concentrions sur le court terme.

À mon avis, la capacité d'écrire une bonne documentation est l'un des traits clés qui distingue les grands programmeurs des programmeurs médiocres.

La personne la mieux qualifiée pour rédiger de la documentation est également celle qui a le moins de motivation pour le faire:

il (ou elle) est:

• principalement un mainteneur de la bibliothèque, plutôt qu'un utilisateur. Donc, plus la bibliothèque est petite et simple, plus son travail est facile. Le maintien d'un demi-roman en plus du code ne fait que rendre son travail plus difficile,
• il connaît la bibliothèque à fond, donc il n'a pas besoin de la documentation,
• il est programmeur, il veut écrire du code, pas de la documentation.

Je ne peux pas penser à quelqu'un qui est moins susceptible d'aller "Hmm, je devrais vraiment passer quelques heures à écrire une documentation appropriée pour cela". Pourquoi le ferait-il?

Et bien sûr, cela n'aide probablement pas qu'il y ait cette légende urbaine qui circule que les commentaires de style doxygen générés automatiquement sont tout ce dont vous avez besoin en termes de documentation.

Donc, même dans les rares cas où un développeur est réellement prêt à écrire de la documentation, il est 50/50 de chances que le développeur ait été soumis à un lavage de cerveau par ce culte en pensant que tout ce qui est nécessaire est de remplir quelques-uns de ces commentaires, en vous disant des joyaux comme que "la fonction Foo getFoo()renvoie un objet de type Foo, et elle est utilisée pour obtenir l'objet Foo".

Documentation? Nous n'avons pas besoin de documentation puante!

Je sais comment fonctionne le code, alors pourquoi passer du temps à documenter mon code? En plus de cela, je dois avoir ce projet fait vendredi et je vais à peine le faire tel quel ...