Devez-vous tout documenter ou juste la plupart?

Cela semble un peu un sujet controversé de tout documenter, y compris la syntaxe "JavaBean" des getters et des setters pour les champs: les gens disent que sa rupture inutilement longue et répétitive DRY (ne vous répétez pas) , que la convention de nommage devrait tout expliquer , et il encombre le code / la documentation. Parfois, ces arguments fonctionnent. Mais d'autres fois, vous vous retrouvez avec ceci:

Ci-dessus est commun aux projets open source qui suivent hardiment ces principes. Vous vous retrouvez avec une documentation entièrement inutile . Cela n'explique rien sur ce qui se passe en dessous, les effets possibles ou même la valeur attendue (pourrait-elle être nulle ou jamais nulle? Je ne sais pas; le Javadoc ne me le dit pas).

Alors, quand dois-je documenter? Dois-je tout documenter même s'il encombre parfois le code? Ou est-ce que je ne documente rien car à mes yeux c'est "évident"?

Tout document qui fait sens pour documenter .

Dans un monde idéal, oui, vous documenteriez tout. Cependant, sur Terre, nous avons des délais, des coupures de fonctionnalités, des familles et des amis à visiter, des vacances à prendre, seulement 24 heures par jour et seulement 365 jours par an. Il n'y a tout simplement pas assez de temps pour tout documenter. Donc, de manière optimale, documentez tout ce que vous pouvez (vous ne le ferez pas), mais obtenez le meilleur pour votre argent en:

• Rendez le code lisible et les signatures de méthode aussi évidentes que possible afin que la documentation soit moins susceptible d'être nécessaire.
• Documenter d'abord les choses les plus obscures. Aidez les autres en documentant les hacks fous que vous avez dû faire pour sortir les choses.
• Documentez le pourquoi avant le quoi - Ne commentez pas ce que fait quelque chose, comme "Itérer sur les enregistrements client où le solde est inférieur à zéro et la note est inférieure à un et les ajouter à la liste des clients exemptés". Indiquez pourquoi vous les ajoutez à la liste en anglais (ou dans la langue de votre équipe), comme "Étant donné que ces clients ont un solde négatif et de faibles notes, ils nous font perdre de l'argent, alors excluez-les de la possibilité de vérifier.

Continuez à documenter jusqu'à ce que vous puissiez regarder quelqu'un d'autre le lire sans ressentir le besoin d'expliquer quoi que ce soit.

La semaine dernière, un excellent article sur la documentation a été publié sur The Daily WTF. Je pense que ça dit tout, donc je vais juste laisser le lien:

http://thedailywtf.com/Articles/Documentation-Done-Right.aspx

Fondamentalement, cela dit que vous ne devriez pas documenter quelque chose si cela ne va pas être utile (une partie de la documentation est juste laissée pourrir dans un tiroir) et documenter le moins d'informations nécessaires pour comprendre une certaine partie du projet. Trop de documentation déroute le lecteur.

Cela dépend vraiment de la lisibilité du code pour le public qui le lit. Déterminez qui est le public pour lire votre code et demandez à quelqu'un qui rencontre ce profil de lire votre code.

Une autre approche consisterait à revoir votre propre code après une semaine et à voir si vous comprenez toujours ce que vous avez fait, si vous ne le faites pas, à le documenter et à revoir le code dans environ deux semaines.

Bien que j'apprécie une documentation claire et complète, il n'y a rien de tel qu'un code auto-documenté. Donc, la ligne de fond (pour moi) est:

Soyez très méfiant vis-à-vis de la documentation (code source); essayez de le rendre redondant en améliorant le code, mais n'hésitez pas à documenter clairement et complètement si nécessaire.

Bien sûr, dans certaines circonstances, la documentation peut être requise pour des raisons autres que «expliquer ce que fait le code» (par exemple: grande équipe, normes d'organisation, etc.).

Ma suggestion sur la documentation est que s'il y a quelque chose de fantaisiste dans le code, cela appartient à un document qui doit être tenu à jour. Je préfère être sujet à beaucoup d'interprétations, dans mon esprit, c'est là où quelque chose est fait d'une manière particulière qui peut avoir des effets secondaires qui devraient être notés, par exemple quelque chose peut être fait de manière récursive pour s'assurer que les éléments des petits-enfants sont traités en passant par un arbre de nœuds pour effectuer un test sur tous les descendants. Expliquer pourquoi quelque chose a été fait d'une manière particulière peut être un bon moyen de savoir s'il y a ou non une bonne raison d'utiliser quelque chose.

En termes simples, la documentation est là pour aider les développeurs maintenant et les mainteneurs à l'avenir.

Si vous vous souvenez de cette maxime simple, le niveau de documentation devrait être auto-défini.

La documentation, par souci de documentation, est une perte de temps ... mais expliquer aujourd'hui ce que vous faites est plus utile que quelqu'un qui doit procéder à une rétro-ingénierie de votre code dans cinq ans.

Personnellement , je vais à l'approche de considérer documentant tout. C'est-à-dire lors du codage, je considère à chaque point si la documentation ajouterait de la valeur. La plupart du temps, la réponse est oui pour exactement les types de contraintes et de connaissances de domaine mentionnés dans la question d'origine. Par exemple, capacité nulle, contraintes uniques, interprétation du champ dans le domaine plus large.

Pour éviter la duplication, j'ai tendance à documenter fortement les principales classes d'API avec ce type d'informations. Ensuite, documentez uniquement les implémentations et les composants internes où il y a un comportement non évident ou incohérent. Je trouve que cela fonctionne bien car ce sont les utilisateurs de l'API qui ont le plus besoin d'aide et de documentation, il est généralement sûr de supposer que les personnes modifiant l'implémentation connaissent l'API et ont donc cette connaissance.

J'ai aussi tendance à documenter uniquement les getters. Je ne reproduis pas la documentation sur les setters, les définitions de champ et les paramètres du constructeur. Je ne documente que les comportements non évidents tels que les valeurs par défaut à ces endroits. Tout comportement pouvant être déduit de la documentation du getter n'est pas documenté. Par exemple, si le getter est documenté comme null jamais retourné, je ne documente généralement pas que vous ne pouvez pas passer null au setter, sauf s'il existe une valeur par défaut.

Certaines personnes aiment marquer cet acte de "considérer la documentation" en ajoutant des commentaires vides là où ils ont considéré la documentation mais l'ont trouvée inutile. Je n'aime pas cette pratique car elle encombre le code et gêne.