Comment documenter le code?
Vous avez déjà un indice: regardez comment l'API Java est documentée.
Plus généralement, il n’existe pas de règles uniques applicables à 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 de taille moyenne .
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 l' écriture de documentation n'est pas assez amusante pour être effectuée 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.
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.
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.
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:
Au début, l'équipe est prête à documenter beaucoup.
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.
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.
Remarquant 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 à toute 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 un renforcement positif / négatif .
(Voir le commentaire de SJuan76 ) Traitez l'absence 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 . Seuls les examens de code et d' autres humains tâches 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.