Etudes sur les gains / pertes de productivité de la documentation du code

Après de nombreuses recherches, je n'ai pas réussi à répondre à une question de base concernant un supposé connu dans le monde du développement logiciel:

CE QUI EST CONNU:

L'application d'une politique stricte sur une documentation de code adéquate (que ce soit les balises Doxygen, Javadoc ou simplement une abondance de commentaires) ajoute des frais généraux au temps requis pour développer du code.

MAIS:

Avoir une documentation complète (ou même une API) entraîne des gains de productivité (on suppose) chez les développeurs nouveaux et chevronnés lorsqu'ils ajoutent des fonctionnalités ou corrigent des bugs en cours de route.

LA QUESTION:

Le temps de développement supplémentaire requis pour garantir une telle documentation est-il compensé par les gains de productivité ultérieurs (au sens strictement économique)?

Je recherche des études de cas ou des réponses qui peuvent apporter des preuves objectives à l'appui des conclusions qui en sont tirées.

Merci d'avance!

L'article "Le style typographique est plus que cosmétique" est assez ancien mais il est très intéressant: http://portal.acm.org/citation.cfm?id=78611 .

Étant vieux, il n'inclut pas tous les trucs fantaisistes qui seraient possibles de nos jours mais cela montre clairement que la documentation du code est importante.

Pour ceux qui, comme moi, n'ont pas accès à la bibliothèque numérique ACM, ils ont créé deux groupes de programmeurs et leur ont donné le même code à étudier. Le groupe A n'a reçu que le code avec les commentaires habituels, le groupe B a reçu une jolie liste imprimée avec table des matières, références croisées et toutes les subtilités qui étaient possibles en 1990.

Ensuite, ils ont demandé aux deux groupes d'effectuer certaines tâches sur le code (par exemple étendre une fonction, trouver un bug, ...) et les ont notés en termes de vitesse et de qualité des réponses.

Pour équilibrer le groupe, ils avaient le même nombre de programmeurs experts et juniors.

Eh bien, il s'est avéré que le groupe B (celui avec une liste assez imprimée) a obtenu un meilleur score que le groupe A dans de nombreux tests. Et, sur des cas spécifiques, seuls les plus experts du groupe A ont réussi à dépasser le programmeur junior du groupe B.

L'article en dit plus, mais c'est ce dont je me souviens de mémoire (je devrais toujours avoir l'article imprimé quelque part).

Pour moi au moins, il semble évident que le code lisible vaut beaucoup plus que la documentation qui ne sert qu'à compenser le code mal écrit. J'ai tendance à considérer les commentaires dans le code comme un défi pour voir si je peux supprimer le commentaire en réécrivant le code et en le rendant plus explicite.

Je ne peux pas étayer cela avec des preuves tangibles, sauf bien, le bon sens.

Je n'ai pas d'études à citer, mais j'ai une règle simple: si je reviens à mon code deux semaines plus tard et que je ne peux pas immédiatement comprendre ce que j'ai fait, il a besoin de plus de commentaires ou doit être simplifié .

Certes, le fonctionnement de votre code doit être documenté par le code lui-même. Mais le temps passé à rédiger des commentaires qui expliquent soigneusement et succinctement pourquoi votre code est écrit de la façon dont il est presque certainement rentabilisé à long terme, même si vous êtes la seule personne qui gère le code.

La durée de vie d'un logiciel sera principalement consacrée à la phase de maintenance, donc tout ce qui aide le programmeur à venir après vous pour comprendre ce qui se passe fournira presque certainement des retours financiers, car cela aide le développeur à se mettre au courant plus rapidement.

Sur toute API légèrement non triviale, la documentation de l'API dans le code est à peu près inutile. C'est parce que la puissance de l'API vient de la façon dont elle fonctionne ensemble comme une unité entière (et non du fonctionnement des méthodes / objets individuels).

Ainsi, plus utile que la vraie documentation est un document de type livre de cuisine qui explique les modèles d'utilisation attendus de l'API, et des exemples de la façon de résoudre certaines situations évidentes (qui utilisent la majorité (et non 100%) de l'API).

La décision de savoir si une méthode donnée est, sans outils qui n'ont probablement pas encore été inventés, trop subjective pour exiger que la documentation soit écrite.

Toutes les meilleures pratiques, telles que «toutes les méthodes publiques» ou toutes les classes dans un package donné, etc., peuvent aider mais sont trop approximatives pour être recommandées au-delà des cas d'utilisation spécifiques.

Ma suggestion: enseignez à vos développeurs les bonnes pratiques, comment identifier les méthodes importantes à documenter (API formelles ou informelles, couramment utilisées, méthodes de stub, complexes ou ésotériques) et laissez-les se gouverner elles-mêmes.

(Étroitement liés: peut-il y avoir trop d'uniformité dans les normes de codage? )

^{Excuses que je n'ai pas d'études à citer, mais je soupçonne que c'est un problème où toute tentative de le mesurer affecterait trop le résultat pour tirer des conclusions générales.}

Je pense que nous devons séparer le code "normal" des API publiques à cet égard. Pour le code ordinaire, je suis venu à être fortement d'accord avec la plupart des autres répondeurs dans ce code devrait être auto-documenté et lire presque comme de la prose . Si mon code n'est pas comme ça, c'est généralement ma faute, donc plutôt que de documenter, il faut le refactoriser. De petites méthodes qui ne font qu'une chose à la fois, travaillant sur un seul niveau d'abstraction, ayant un nom correct et descriptif , peuvent grandement contribuer à y parvenir.

Le problème avec les commentaires, c'est qu'ils pourrissent. Dès que vous ajoutez un commentaire, il commence à vivre une vie indépendante du code qu'il accompagne. Quelle est la probabilité que le prochain développeur qui modifie le code mette à jour consciencieusement le ou les commentaires associés? D'après mon expérience, près de zéro. Le résultat final après quelques modifications est que le commentaire intrigue ou induit les gens en erreur au lieu de les aider.

Les exceptions possibles sont le code optimisé pour les performances ou l'utilisation d'un algorithme spécifique . Dans ce cas, il est utile d'ajouter des commentaires pour décrire pourquoi le code ressemble à lui, une référence à l'algorithme, etc.

Le travail fondateur sur ce sujet est Clean Code .

OTOH une API publique devrait également être bien documentée dans Javadoc . Puisqu'il peut être utilisé par d'innombrables inconnus avec des compétences et des hypothèses extrêmement variées, il faut prendre toutes les précautions pour le rendre aussi simple et sans ambiguïté que possible. C'est encore largement une question de conception correcte de l'API, mais la documentation a également un rôle important à jouer.

La question est de savoir si vous gagnez du temps en documentant votre code par rapport à chaque développeur suivant qui doit essayer de comprendre ce qui se passe. Si votre code passe par la révision du code sans que personne ne pose de questions sur ce qu'il fait, vous êtes probablement en bonne forme. Il n'est pas trop difficile de décrire les hypothèses que vous faites sur les entrées. Supposons que votre méthode prenne un objet entier et renvoie un objet chaîne. Est-ce que l'int est nul? Y a-t-il une valeur min / max (en plus de integer.MinValue / MaxValue)? Peut-il retourner une chaîne vide ou null? Jette-t-il des exceptions? Bien sûr, tout le monde peut les trouver par inspection, mais si suffisamment d'autres développeurs vont utiliser votre code, les enregistrer chacun quelques minutes en vaut la peine. En outre, cela donne aux testeurs une longueur d'avance sur la création de tests pour confirmer votre code.

C'est certainement un sujet intéressant car il y a toujours eu des arguments pour savoir si le développeur devrait passer du temps à créer ou à maintenir des documents ou non, mais le fait est que le code doit être bien écrit et très bien commenté, de cette façon lorsque le développeur revoit le code qu'il ou elle. n'a pas à passer du temps à réfléchir à la façon dont le code a été écrit et à ce qu'il était censé faire en premier lieu si un nouveau membre de l'équipe se joint à l'équipe, il peut également comprendre la fonctionnalité et le fonctionnement du code tel qu'il a été clairement documenté.

Ainsi, le code doit être très bien commenté et doit donc être un code auto-documenté qui ne nécessite aucune documentation externe.

Dans ma carrière, j'ai vu du code avec différents niveaux de documentation et de qualité (notez que la documentation et la qualité sont des préoccupations orthogonales). Je préférerais que le temps consacré à la documentation soit utilisé pour améliorer la qualité. Pour le cas simple, il existe des outils comme GhostDoc qui peuvent regarder une fonction et générer des commentaires de doc pour vous. Si GhostDoc peut générer un commentaire significatif qui dit ce que fait votre fonction, alors vous avez évidemment atteint l'objectif d'avoir des fonctions bien nommées.

Dans de nombreux cas, GhostDoc ne peut même pas commencer à vous dire ce que fait réellement une fonction. Il est préférable de passer votre temps à résoudre ce problème et (peut-être) à utiliser ghostdoc pour générer automatiquement votre code.

Voir Clean Code et PPP de Bob Martin pour une discussion plus approfondie.