Il existe de bons exemples de code bien documenté, comme java api. Mais, beaucoup de code dans les projets publics tels que git et les projets internes des entreprises est mal documenté et pas très convivial pour les nouveaux arrivants.

Au cours de toutes mes étapes de développement logiciel, jai dû faire face à du code mal documenté. Jai 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 existe peu ou pas de documentation sur la manière dont le code sintè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, jai dû passer par beaucoup de coder et parler à de nombreuses personnes pour apprendre des choses. Je pense que cela fait perdre du temps à tout le monde. Cela crée également le besoin de sessions de transfert de connaissances / connaissances pour les nouveaux arrivants à un projet.

Jai appris que la documentation ne reçoit pas lattention quelle mérite pour les raisons suivantes:

  1. Paresse.
  2. Les développeurs naiment pas faire autre chose que du code.
  3. Sécurité de lemploi. (Si personne ne peut facilement comprendre votre code, vous ne serez peut-être pas facilement remplaçable.)
  4. Les délais difficiles laissent peu de temps pour documenter.

Je me demande donc sil existe un moyen dencourager et de faire appliquer les 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é? Y a-t-il de bons exemples de cas où une documentation minimale ou nulle est nécessaire?

À mon humble avis, je pense que nous devrions avoir un examen de la documentation après la livraison dun projet. Sil nest pas simple, concis, illustratif et convivial, le développeur ou lingénieur en documentation technique en assume la responsabilité et doit être obligé de le corriger. Je nattends pas non plus que les gens fassent des tonnes de documentation, pas espérer quil sera convivial comme les livres tête première, mais je mattends à ce quil élimine le besoin de des heures danalyse et des sessions KT inutiles.

Y a-t-il un moyen de mettre fin ou datténuer cette folie? «Développement piloté par les documents» peut-être?

Commentaires

  • Il y a une autre raison pour laquelle il ny a souvent pas de documentation appropriée: il est très difficile décrire une bonne documentation qui ne ‘ t juste paraphraser le code en anglais, mais décrit pourquoi le code est conçu / écrit de cette façon. Le besoin de ces informations ne devient évident que des mois après quelles auraient dû être écrites.
  • Autre raison sérieuse: de nombreux développeurs ont langlais comme deuxième langue et / ou écrivent mal langlais . Vous pouvez simplement les forcer à écrire une seule ligne pour une méthode, mais si vous voulez une bonne documentation, vous feriez mieux dêtre prêt à payer pour cela et dembaucher des spécialistes pour le faire.

Réponse

Comment documenter le code?

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

Plus généralement, il nexiste pas de règles uniques applicables à chaque projet. Lorsque je travaille sur des projets à grande échelle critiques pour lentreprise, la documentation na rien à voir avec celle que jécrirais pour une petite bibliothèque open source, qui, à son tour, na 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 cest amusant. La plupart des programmeurs et développeurs considèrent que écrire de la documentation nest pas assez amusant pour être fait gratuitement.

Pourquoi de nombreux projets à source fermée ne sont pas bien documentés?

Parce quil en coûte énormément dargent pour (1) rédiger une bonne documentation et (2) la maintenir.

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

  2. Le lo Le coût à terme (coût de la maintenance de la documentation) devient également assez facile pour les gestionnaires et est souvent la première cible lorsquils doivent réduire le coût ou raccourcir les délais. Cela pose un problème supplémentaire de documentation obsolète qui devient rapidement inutile et est extrêmement coûteuse à mettre à jour.

  3. Les économies à long terme (économies de ne pas avoir à perdre quelques jours à explorer le 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 gestionnaires que la rédaction et la maintenance de la documentation sont une perte de temps.

Ce que jobserve souvent, cest 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 dinté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 réel.

  4. Remarquant que, la direction blâme les développeurs pour ne pas conserver la documentation; les développeurs demandent à passer quelques semaines à le mettre à jour.

    • Si la direction accorde quelques semaines pour cela, le cycle se répète.

    • Si la direction refuse, sur la base de lexpérience précédente, cela ne fait quaugmenter la mauvaise expérience, car le produit manque de documentation, mais quelques mois ont été consacrés à lécrire et à le maintenir.

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

Comment encourager léquipe à écrire documentation?

De la même manière que les moyens dencourager les gens à écrire du code propre, à faire du refactoring régulier, à utiliser des modèles de conception ou à ajouter suffisamment de tests unitaires.

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

  • 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 pas du tout), discutez du sujet avec eux en privé, pour comprendre quels sont les obstacles qui les empêchent de rédiger une meilleure documentation. Sils blâment le manque de temps, vous voyez la source des problèmes.

  • Rendez la présence ou le manque de documentation mesurables pendant quelques semaines ou quelques mois, mais ne « t Concentrez-vous sur cela. Par exemple, vous pouvez mesurer le nombre de lignes de commentaires par LOC, mais nen 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 vient avec le point précédent.

  • Utilisez un renforcement positif / négatif .

  • (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 une documentation XML. Si vous vérifiez également que tous les avertissements sont traités comme des erreurs, labsence de commentaire en tête dune classe ou dune méthode arrêtera la compilation.

    Comme pour les trois points précédents, celui-ci doit être utilisé Avec précaution. Je lai utilisé pendant un certain temps avec une équipe particulièrement difficile de programmeurs débutants, et il sest retrouvé avec des commentaires conformes à StyleCop comme celui-ci: 

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

qui nétaient, hum …, pas particulièrement utiles.

Noubliez pas: rien dautomatisé ne peut vous aider à identifier les mauvais commentaires lorsque les programmeurs veulent vous baiser . Seul le code les critiques et autres tâches humaines vous aideront.

Y a-t-il de bons exemples de cas où une documentation minimale ou nulle est nécessaire?

La documentation expliquant larchitecture et le design nest 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ù cest évident, compte tenu sa petite taille, associée à un code particulièrement propre, que vous passerez plus de temps à écrire de la documentation que tous les futurs responsables à explorer le code.

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

Je pense que nous devrions avoir une revue de la documentation après la livraison dun projet.

Si votre projet est livré au moins une fois par semaine, cest la voie à suivre. Si votre projet nest pas agile et est livré tous les six mois, effectuez des révisions plus régulières.

Commentaires

  • À ‘ comment encourager ‘, jajouterais que de nombreux IDE permettent la notification de la documentation manquante sous forme davertissements. Alternativement, peut-être quune analyse statique de la documentation peut être effectuée au BSF (bien sûr, cela ne suffirait pas à lui seul).
  • @ SJuan76: En effet. Visual Studio peut même traiter labsence de commentaires comme une erreur de compilation. Jai édité ma réponse pour ajouter une note à ce sujet.
  • @ArseniMourzenko – Jai lu que nous pourrions encourager une certaine documentation dans Agile en ajoutant des histoires pour la documentation. Mais, ceux-ci ne doivent pas bloquer les autres histoires, cest-à-dire que la définition des autres histoires de done, ne doit pas inclure lachèvement des histoires de documentation. Comment cela vous semble-t-il?
  • @ArseniMourzenko – Je ‘ voudrais ajouter deux points supplémentaires à votre réponse. (1) Dans Jira etc., ajoutez une tâche pour la documentation tout le temps. (2) Faites réviser les documents par 2 autres personnes & mettez cela aussi comme une tâche. De cette façon, les gens se verront rappeler de document & évitera décrire des documents de mauvaise qualité (en raison de la révision). Si vous ne le ‘ ne donnez pas la priorité &, alors il deviendra mauvais. Je sais quAmazon effectue beaucoup de & critiques de documents, peut-être un peu trop.

Réponse

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 plutôt indiquer aux autres programmeurs des parties délicates.

La documentation du code 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 sy opposer documenter les connaissances? Heureusement, le développement de logiciels nest pas de la science, et le monde ne seffondre pas si les détails de votre petit programme deviennent obscurs. Maintenant concernant un logiciel professionnel destiné à de nombreux développeurs, oui évidemment vous devez documenter votre code. Mais si vous êtes en mesure coder à ce niveau, alors vous le sauriez évidemment.

tl; dr

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

Commentaires

  • Fortunately software development is not science Veuillez men dire plus sur les raisons pour lesquelles vous pensez cela.
  • @Borat – Le développement logiciel est une discipline dingénierie, ce qui implique quil utilise les outils fournis par la science.
  • Je ne demande pas que tout soit documenté. Cela devrait être juste assez pour donner un aperçu de haut niveau de ce que font un système et un code. Par exemple, dites-moi comment utiliser mon téléviseur. ‘ ne me soucie pas sil utilise un écran LCD, CRT, Tubes à vide ou dispositifs à semi-conducteurs pour faire le travail . Si un réparateur veut cette information, créez une documentation séparée pour lui.
  • Si vous voulez une vue densemble de haut niveau, les noms didentifiants suffisent. Tout comme le bouton de votre téléviseur peut avoir une étiquette  » On « . Donc vous demandez des détails de bas niveau.
  • @LeopoldAsperger: Je pense que Borat parle de documenter larchitecture et la conception, pas les méthodes dans les classes.

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *