Comment faire de la documentation pour le code et pourquoi les logiciels sont-ils (souvent) mal documentés?

Question

Il existe de bons exemples de code bien documenté, tels que Java api. Mais, beaucoup de code dans les projets publics tels que git et les projets internes des entreprises est mal documenté et peu accueillant pour les nouveaux arrivants.

Dans tous mes séjours de développement logiciel, j'ai dû faire face à du code mal documenté. J'ai remarqué les choses suivantes -

1. Peu ou pas de commentaires dans le code.
2. Les noms de méthode et de variable ne sont pas auto-descriptifs.
3. Il y a peu ou pas de documentation sur la façon dont le code s'intègre dans le système ou les processus métier.
4. Embaucher de mauvais développeurs ou ne pas encadrer les bons. Ils ne peuvent pas écrire de code simple et propre. Par conséquent, il est difficile ou impossible pour quiconque, y compris le développeur, de documenter le code.

En conséquence, j'ai dû passer par beaucoup de code et parler à beaucoup de gens pour apprendre des choses. Je pense que cela fait perdre du temps à tout le monde. Cela crée également le besoin de sessions KT/transfert de connaissances pour les nouveaux arrivants dans un projet.

J'ai appris que la documentation ne reçoit pas l'attention qu'elle mérite pour les raisons suivantes:

1. Paresse.
2. Les développeurs n'aiment pas faire autre chose que du code.
3. La sécurité d'emploi. (Si personne ne peut comprendre votre code facilement, il se peut que vous ne soyez pas facilement remplaçable.)
4. Des délais difficiles laissent peu de temps pour documenter.

Je me demande donc s'il existe un moyen d'encourager et d'appliquer de bonnes pratiques de documentation dans une entreprise ou un projet. Quelles sont les stratégies à utiliser pour créer une documentation décente pour les systèmes et le code de tout projet, quelle que soit sa complexité? Existe-t-il de bons exemples de documentation minimale ou inexistante?

À mon humble avis, je pense que nous devrions avoir un examen de la documentation après la livraison d'un projet. S'il n'est pas simple, concis, illustratif et convivial, le développeur ou l'ingénieur en documentation technique en est responsable et doit le réparer. Je ne m'attends pas non plus à ce que les gens fassent des tonnes de documentation, je n'espère pas qu'elle sera conviviale comme les premiers livres, mais je m'attends à ce qu'elle élimine le besoin d'heures d'analyse et de sessions KT inutiles.

Existe-t-il un moyen de mettre fin ou d'atténuer cette folie? "Développement axé sur les documents" peut-être?

Answer 1

Comment documenter le code?

Vous avez déjà un indice: regardez comment Java API est documenté.

Plus généralement, il n'y a pas d'ensemble unique de règles qui s'appliquent à chaque projet. Lorsque je travaille sur des projets à grande échelle critiques pour l'entreprise, la documentation n'a rien à voir avec celle que j'écrirais pour une petite bibliothèque open source, qui, à son tour, n'a rien à voir avec la documentation de mon projet personnel à moyenne échelle .

Pourquoi de nombreux projets open source ne sont pas bien documentés?

Parce que la plupart des projets open source sont réalisés par des personnes qui contribuent à ces projets parce que c'est amusant. La plupart des programmeurs et développeurs considèrent que écrire de la documentation n'est pas assez amusant pour être fait gratuitement.

Pourquoi de nombreux projets de sources fermées ne sont pas bien documentés?

Parce qu'il en coûte énormément d'argent pour (1) écrire une bonne documentation et (2) la maintenir.

1. Le coût immédiat (coût de rédaction de la documentation) est clairement visible pour les parties prenantes: si votre équipe demande à passer les deux prochains mois à documenter le projet, c'est deux mois supplémentaires de salaire à payer.

2. Le coût à long terme (coût de la maintenance de la documentation) devient également assez facile à comprendre pour les gestionnaires, et est souvent la première cible lorsqu'ils doivent réduire le coût ou raccourcir les délais. Cela entraîne un problème supplémentaire de documentation obsolète qui devient rapidement inutile et dont la mise à jour est extrêmement coûteuse.

3. Les économies à long terme (économies de ne pas avoir à perdre quelques jours à explorer le code hérité juste pour comprendre un élément de base qui aurait dû être documenté il y a des années) sont, en revanche, difficiles à mesurer, ce qui confirme le sentiment de certains managers que la rédaction et la maintenance de la documentation est une perte de temps.

Ce que j'observe souvent, c'est que:

1. Au début, l'équipe est prête à documenter beaucoup.

2. Au fil du temps, la pression des délais et le manque d'intérêt rendent de plus en plus difficile la maintenance de la documentation.

3. Quelques mois plus tard, une nouvelle personne qui rejoint le projet ne peut pratiquement pas utiliser la documentation, car elle ne correspond pas du tout au système actuel.

4. Constatant que, la direction reproche aux développeurs de ne pas maintenir la documentation; les développeurs demandent à passer quelques semaines à le mettre à jour.

   • Si la direction accorde quelques semaines pour cela, le cycle recommence.

   • Si la direction refuse, sur la base d'une expérience antérieure, cela ne fait qu'augmenter la mauvaise expérience, car le produit manque de documentation, mais quelques mois ont été consacrés à sa rédaction et à sa maintenance.

La documentation doit être un processus continu, tout comme les tests. Passez une semaine à simplement coder quelques milliers de LOC, et revenir aux tests et à la documentation est très, très douloureux.

Comment encourager l'équipe à rédiger de la documentation?

De la même manière que pour encourager les gens à écrire du code propre, à refactoriser régulièrement, à utiliser des modèles de conception ou à ajouter suffisamment de tests unitaires.

• Mener par l'exemple. Si vous écrivez une bonne documentation, vos paires pourraient aussi commencer à le faire.

• Faites des revues de code systématiques, y compris des revues de code formelles visant à inspecter la documentation.

• Si certains membres de l'équipe sont particulièrement antipathiques à une bonne documentation (ou à une quelconque documentation), discutez du sujet avec eux en privé, pour comprendre quels sont les obstacles qui les empêchent de rédiger une meilleure documentation. S'ils blâment le manque de temps, vous voyez la source des problèmes.

• Rendez la présence ou le manque de documentation mesurable pendant quelques semaines ou mois, mais ne vous concentrez pas là-dessus. Par exemple, vous pouvez mesurer le nombre de lignes de commentaires par LOC, mais n'en faites pas une mesure permanente, sinon les développeurs commenceront à écrire des commentaires longs mais dénués de sens juste pour se débarrasser des scores faibles.

• Utilisez la gamification. Cela rejoint le point précédent.

• Utilisez positif/négatif renforcement .

• (Voir le commentaire de SJuan76 ) Traitez le manque de commentaires comme des erreurs. Par exemple, dans Visual Studio, vous pouvez cocher une option pour générer la documentation XML. Si vous vérifiez également que tous les avertissements sont traités comme des erreurs, l'absence de commentaire en haut d'une classe ou d'une méthode arrêtera la compilation.

  Quant aux trois points précédents, celui-ci doit être utilisé avec prudence. Je l'ai utilisé pendant un certain temps avec une équipe de programmeurs débutants particulièrement solide, et il s'est retrouvé avec des commentaires conformes à StyleCop comme ça:

    /// <summary>
    /// Gets or sets the PrimaryHandling.
    /// </summary>
    public Workflow PrimaryHandling { get; set; }

qui étaient, hm ..., pas particulièrement utiles.

Rappelez-vous: rien d'automatisé ne peut vous aider à localiser les mauvais commentaires lorsque les programmeurs veulent vous baiser . Uniquement les revues de code et autres human les tâches vous aideront.

Existe-t-il de bons exemples de documentation minimale ou inexistante?

La documentation expliquant l'architecture et la conception n'est pas nécessaire:

• Pour un prototype,

• Pour un projet personnel écrit en quelques heures pour accomplir une tâche, tout en étant sûr que ce projet ne sera plus maintenu,

• Pour tout projet où il est évident, compte tenu de sa petite taille, couplé au code particulièrement propre, que vous passerez plus de temps à rédiger de la documentation que tous les futurs mainteneurs explorant le code.

La documentation en code (commentaires de code) n'est pas nécessaire selon certains développeurs lorsque le code est auto-documenté. Pour eux, la présence de commentaires n'est, sauf dans les rares cas, pas un bon signe, mais un signe que le code n'a pas été suffisamment refactorisé pour être clair sans avoir besoin de commentaires.

Je pense que nous devrions avoir un examen de la documentation après la livraison d'un projet.

Si votre projet est livré au moins une fois par semaine, c'est la voie à suivre. Si votre projet n'est pas agile et est livré à intervalles de six mois, faites des révisions plus régulières.

Answer 2

Je pense que vous devriez faire une distinction entre les commentaires et la documentation. Bien que les commentaires soient descriptifs, ils manquent de cohérence, ils sont dispersés dans tout le code. Les commentaires ne devraient jamais compenser le code qui ne se décrit pas suffisamment, mais devraient plutôt indiquer aux autres programmeurs les parties délicates.

La question de savoir si le code doit être documenté dépend de l'échelle du projet. Il y a sûrement des gens qui croient que tout devrait être documenté, et il semble facile de justifier cette pensée car qui oserait s'opposer à la documentation des connaissances? Heureusement, le développement de logiciels n'est pas une science et le monde ne s'effondre pas si les détails derrière votre petit programme deviennent obscurs. Concernant maintenant un logiciel professionnel destiné à de nombreux développeurs, oui, vous devez évidemment documenter votre code. Mais si vous êtes en mesure de coder à ce niveau, vous le saurez évidemment.

tl; dr

Si vous demandez que chaque projet soit bien documenté, vous en demandez trop.