Combien de documentation suffit?

Combien de documentation technique (pour les futurs développeurs) est suffisante ? Y a-t-il un rapport entre les heures de codage et les heures de documentation qui est approprié?

Papadimoulis soutient que vous devriez

produire le moins de documentation nécessaire pour faciliter la compréhension,

Est-ce une bonne ligne directrice ou y a-t-il des choses spécifiques que je devrais créer?

Que diriez-vous de quelques tests d'utilisabilité du couloir? Montrez le code et la documentation à un développeur qui ne connaît pas le projet. Lorsque vous pouvez le faire sans une envie écrasante d'expliquer quelque chose tout en les regardant revoir le code, vous en avez assez.

La perfection est atteinte non pas quand il n'y a plus rien à ajouter, mais quand il n'y a plus rien à retirer.
Antoine de Saint-Exupéry

Je réfléchis à ce sujet depuis un moment.

Ma conclusion est - ce n'est pas une question de quantité, mais de qualité et de contexte.

Par exemple, une structure de projet appropriée bat les commentaires expliquant où se trouvent les fichiers (implémentation vs intension)

De même, la classification pour clarifier le contexte bat la dénomination (Id sur un patient -> Patient.Id).

Je crois que DDD a son mot à dire dans une bonne documentation - la classification fournit le contexte, le contexte crée des limites et les limites mènent à des implémentations intentionnelles (c'est là que cela appartient, plutôt que d'exister).

Le code en soi n'est pas assez bon pour être considéré comme de la documentation. Le problème dans la plupart des cas ne réside pas dans le fait que le fonctionnement des codes est commenté ou non, mais plutôt la force motrice (logique du domaine) ne l'est pas.

Nous oublions parfois qui est le patron - si le code change, la logique ou le raisonnement du domaine ne devrait pas, mais si la logique ou le raisonnement du domaine change, le code le sera certainement.

La cohérence est également très importante - la convention en soi est inutile si elle n'est pas cohérente.

Les modèles de conception ne sont pas seulement des «bonnes pratiques» - c'est un langage que les développeurs doivent comprendre. Il est préférable de dire à un développeur d'ajouter un nouveau type à une usine que d'ajouter un nouveau type à une méthode (où le contexte et la cohérence sont faibles ou manquants).

La moitié de la lutte est la familiarité .

Par ailleurs, les API qui semblent favoriser beaucoup de documentation sont également très sensibles au domaine et au contexte. Parfois, la duplication de fonctionnalités n'est pas mauvaise (même chose, différents contextes) et doit être traitée comme distincte.

En termes de commentaires, il est toujours bon de souligner la logique du domaine derrière le raisonnement.

Par exemple, vous travaillez dans l'industrie médicale. Dans votre méthode, vous écrivez "IsPatientSecure = true;"

Maintenant, tout programmeur décent peut comprendre que le patient est marqué comme sécurisé. Mais pourquoi? Quelles en sont les implications?

Dans ce cas, le patient est un détenu qui a été transféré en toute sécurité dans un hôpital hors établissement. Sachant cela, il est plus facile d'imaginer les événements qui ont mené à ce point (et peut-être ce qui doit encore se produire).

Peut-être que ce post semble au mieux philosophique - mais rappelez-vous que c'est le «raisonnement» ou la «logique» que vous écrivez - pas le code.

Je suis d'accord avec la citation de Papadimouslis. Le code source peut parler de lui-même, mais le code ne peut pas vous dire pourquoi il existe, comment il doit être utilisé et comment le code doit se comporter.

Je ne connais pas un bon ratio.

J'ai hérité de centaines de lignes de code avec très peu de documentation. Il m'est devenu difficile de comprendre pourquoi le code avait été écrit. Après avoir découvert pourquoi le code a été écrit, j'ai dû comprendre comment utiliser le code. Après avoir découvert cela, j'ai dû comprendre comment il est supposé se comporter afin que je puisse prendre en charge et maintenir le code.

Par expérience, ne faites pas de commentaires trop spécifiques ou vous finirez par devoir maintenir le code réel ET la documentation. C'est un cauchemar lorsque la documentation et le code ne sont pas synchronisés.

De quoi vous faire arrêter de vous deviner.

Si à n'importe quel moment de votre travail vous vous dites "hmm, je devrais peut-être documenter cela", allez-y et faites-le. Ensuite, si vous avez écrit de la documentation et que vous vous dites "peut-être que je devrais l'expliquer davantage", allez-y et faites-le.

Rincez-répétez jusqu'à ce que cette sensation disparaisse.

J'ai trouvé qu'une approche axée sur le risque telle que celle présentée dans le livre de George Fairbanks Just Enough Software Architecture fonctionne extrêmement bien pour comprendre la quantité de documentation suffisante. Vous pouvez lire la section qui présente ce concept (chapitre 3) sur son site Web mais l'idée principale est de:

• Exprimer les choses qui vous inquiètent au sujet de la «compréhension du système» comme des risques
• Prioriser les risques
• Atténuez les risques jusqu'à ce que votre équipe estime que le risque du projet a été suffisamment réduit. Dans ce cas, vous allez probablement créer une sorte de documentation.

Pour aider à calibrer les préoccupations afin que vous puissiez hiérarchiser les risques, j'ai trouvé utile d'identifier quelques objectifs connus sous le nom de seuil de réussite , c'est-à-dire l'ensemble minimal d'objectifs que votre équipe pense qu'un projet «réussi» doit atteindre. Du point de vue de la documentation, un exemple de ToS pourrait être quelque chose comme "Un développeur devrait être en mesure de créer un plug-in simple dans les 4 heures suivant la première utilisation du framework."

Identifiez maintenant certains risques. Avec le système que vous avez construit (ou construisez), quelles sont les choses qui inquiètent le plus votre équipe? Formulez-les comme des déclarations de risques. J'aime le style condition-conséquence du SEI mais il y en a d'autres. Exemples:

• Le modèle de données est vaste et complexe; les développeurs peuvent ne pas savoir quels éléments de données utiliser dans une situation donnée.
• Le système a des limites de connexion API pour augmenter la fiabilité; les développeurs peuvent accidentellement dépasser la limite de connexion.
• Les plug-ins sont consommés en plusieurs étapes séquentielles; les développeurs peuvent ne pas créer de plug-ins avec ces étapes ordonnées à l'esprit.

Maintenant en équipe, priorisez les risques. Le vote multiple fonctionne extrêmement bien.

Atténuez les risques prioritaires et répétez en commençant par l'identification jusqu'à ce que le risque d'échec de votre projet (défini par le seuil de réussite) soit dans une limite tolérable. En général, cela signifie que vous aurez des risques qui, selon l'équipe, ne sont pas très préoccupants. Gardez à l'esprit que vous ne voudrez probablement pas atténuer tous les risques. Un exemple de stratégie d'atténuation pour le dernier risque ci-dessus pourrait être de créer un didacticiel.

Le moins possible, mais autant que nécessaire

Je ne me souviens pas où et quand j'ai entendu cela pour la première fois, mais c'est une maxime avec de nombreuses applications.

Plus la technologie ou l'application est complexe, plus la documentation est nécessaire (évidemment), mais il est clair que vous ne voulez pas perdre de temps à passer par dessus bord.

Le «test de couloir» de JohnFx est solide. Mais faites-vous confiance; vous avez développé le code, et vous devez donc avoir une idée des éléments qui nécessitent une attention supplémentaire et des éléments qui seront évidents pour tous. Pensez aux difficultés que vous avez eues à développer le code et vous aurez probablement une idée de ce qu'un autre développeur verra lorsqu'il examinera votre code.

Oubliez toute relation entre l'effort passé à coder et l'effort passé à documenter.

Je crois que vous ne pouvez pas mettre cela dans des règles exactes. La raison de la documentation est de fournir les connaissances difficiles à recueillir à partir du code brut sous une forme afin que d'autres puissent comprendre et peut-être même maintenir ledit code brut.

Par conséquent, la seule façon de savoir si vous en avez suffisamment documenté est de demander au public cible s'il est suffisamment bon. Je pense que le processus «d'examen par les pairs» est très efficace pour le faire dès le départ. Notez combien d'explications sont nécessaires pour que vos pairs comprennent de quoi vous parlez, et travaillez pour minimiser cela.

Si vous ne l'avez jamais fait auparavant, vous ne pouvez pas estimer la quantité de travail qu'il faudra, mais après quelques itérations, vous aurez une bien meilleure idée de la quantité nécessaire.