Pensez-vous que le code est auto-documenté? [fermé]

C'est une question qui m'a été posée il y a de nombreuses années en tant que diplômée lors d'un entretien d'embauche et qui me tourmente le cerveau de temps en temps et je n'ai jamais vraiment trouvé de bonne réponse qui me satisfasse.

L'intervieweur en question cherchait une réponse en noir et blanc, il n'y avait pas de compromis. Je n'ai jamais eu la chance de poser des questions sur la justification de la question, mais je suis curieux de savoir pourquoi cette question serait posée à un développeur et ce que vous apprendrez d'une réponse oui ou non?

De mon propre point de vue, je peux lire Java, Python, Delphi, etc. vous commencez à m'abattre, j'ai entendu cela prononcé dans quelques bureaux par des développeurs), comment est-ce que c'est auto-documenté? Toutes mes excuses si cette question semble étrange, mais je préfère demander et obtenir des opinions à ce sujet pour mieux comprendre pourquoi elle serait posée à quelqu'un dans une interview.

Partiellement.

Le code qui utilise de grands mots anglais peut être partiellement auto-documenté en ce que les noms de toutes les fonctions et variables peuvent vous dire ce qu'il fait. Mais cela ne vous dira probablement pas pourquoi.

Comparer:

a->b;
# what is b doing? what is the a object?

carEngine->startIgnition;
# much more clear what objects are involved

Mais vous ne savez toujours pas pourquoi une voiture démarre. Par conséquent, seulement partiellement. C'est un peu terrible que votre intervieweur s'attende à une réponse en noir et blanc, à moins que sa vision du noir et blanc n'inclue peut-être une très forte opinion.

Non. Le code en soi n'est pas auto-documenté.

La raison en est que le code indique COMMENT et ne se soucie pas POURQUOI, ce que les humains doivent savoir pour maintenir le code.

Par conséquent, vous avez besoin de commentaires supplémentaires expliquant tous les POURQUOI . Vous pouvez les limiter en laissant vos noms de variables inclure une partie des décisions, mais vous ne pouvez pas les éviter.

Le bon code vous dit " comment ". Des commentaires appropriés vous disent " pourquoi " .

Par conséquent, le code peut auto-documenter la façon dont les choses sont réalisées, mais vous ne pouvez pas supposer qu'il documente la raison.

S'ils insistent sur une réponse en noir et blanc sans aucun compromis, la réponse est non.

La réponse la plus complète est que le code devrait être auto-documenté dans toute la mesure du raisonnable, mais il n'y a aucun moyen raisonnable d'inclure certains types de documentation dans le code. Par exemple, le code pourrait très bien simplement documenter les informations collectées sur le formulaire A, celles du formulaire B et celles du formulaire C. Il ne tentera généralement pas (et ne devrait probablement pas) de documenter les tests montrant cette division les données ainsi réduites des erreurs x% par rapport à (par exemple) l'utilisation de seulement deux formulaires au lieu de trois.

Tout sauf le morceau de code le plus trivial peut bénéficier d'au moins une documentation extérieure.

Ma réponse. Dans la mesure du possible, vous devez vous efforcer de rendre votre code aussi documenté que possible. Il y a plusieurs raisons à cela. Lors de l'écriture initiale, une moyenne d'une ligne sur 10 comporte une erreur. Les erreurs de code ont tendance à être trouvées et corrigées. Des erreurs dans la documentation ont tendance à être laissées. Et en maintenance, il est courant que le code et la documentation s'éloignent.

Cela dit, il y a des limites à ce qui peut être fait en rendant le code clair. Dans ces cas, vous devez documenter.

Qu'en est-il du cas où vous avez le choix de documenter? À mon avis, la maintenance dépend fortement de votre organisation. Si vous avez d'excellents développeurs de logiciels et un processus de révision de code rigoureux (comme, par exemple, Google le fait), alors votre processus et les gens peuvent être tels que vous n'avez pas besoin d'être aussi préoccupé par les commentaires qui ne sont pas maintenus. Dans ce cas, un style beaucoup plus lourd de commentaires a beaucoup de sens. (Google a, en fait, un style lourd de commentaires.) Cependant, si vous avez une organisation plus typique, je vais me méfier fortement des commentaires que je vois, et j'espère que vous avez eu des gens qui ont cru en essayant de rendre le code auto-documenté. Dans cette situation, je considérerai les commentaires comme superflus.

Pour une conversation intéressante sur les avantages et les inconvénients des commentaires, voir http://www.perlmonks.org/index.pl?node_id=65153 pour une ancienne conversation à laquelle je faisais partie. (Remarque: en même temps que nous avons eu cette conversation, il y avait un ensemble privé de conversations plus amicales. J'ai toujours regretté que seule la moitié la plus négative de la conversation soit publique.) Mes opinions ne correspondent plus exactement à ce que je pensais alors , mais je pense toujours que la conversation a matière à réflexion.

Je trouve que cette question revient souvent et a souvent une ferveur religieuse. Voici mon point de vue à ce sujet ...

Dans un monde idéal, la déclaration suivante pourrait être faite:

Le code doit être écrit de telle manière que la logique puisse être suivie sans avoir besoin de commenter.

D'accord, c'est assez juste, mais le problème est que nous ne vivons pas dans un monde idéal. La réalisation de cette déclaration idéale pose certains problèmes.

1. Les programmeurs ne sont souvent pas les experts de l'industrie contre laquelle ils programment. Il est assez facile de comprendre une fonction telle que startEngine(Car car)(la plupart) tout le monde peut comprendre ce qui est demandé ici. Mais passez au monde réel, et les choses deviennent un peu plus floues. Par exemple, la fonction getSess(String tid, String aid)serait parfaitement compréhensible pour un ingénieur des transports qui comprenait les systèmes DWDM, mais elle peut représenter un défi pour le nouveau programmeur qui vient de mettre sur le projet. Des commentaires bien placés peuvent aider à faciliter la transition vers la compréhension du code en temps opportun.

2. Les programmeurs invités à maintenir le code ne sont souvent pas aussi qualifiés que les architectes originaux du code. Le programmeur d'origine peut avoir été suffisamment qualifié pour écrire un algorithme rapide, succinct et efficace pour accomplir une tâche spécifique. Mais le programmeur chargé de maintenir ce code peut avoir du mal à essayer de comprendre ce qui se passe. Des commentaires bien placés peuvent aider à faciliter la transition vers la compréhension du code en temps opportun.

3. Combien de fois avez-vous écrit un peu de code, que vous avez par la suite eu du mal à comprendre pourquoi vous avez fait cela, ou même ce que vous tentiez d'accomplir? Nous le faisons tous de temps en temps. Résoudre un problème et produire une solution facile à suivre à un problème sont souvent deux mentalités différentes. À moins que vous ne soyez la personne qui puisse parfaitement écrire du code, vous faites souvent beaucoup de faux pas avec votre code au fur et à mesure. Vous pouvez également ne pas être en mesure de revenir à ce morceau de code pendant un certain temps. Des commentaires bien placés peuvent aider à faciliter la transition vers la compréhension du code en temps opportun.

4. Les situations uniques nécessitent une explication. Par exemple, un programmeur peut se demander pourquoi une pause de 100 ms a été insérée dans un peu de code communiquant avec un périphérique DWDM. Faire savoir au prochain programmeur qu'une pause est nécessaire parce que l'appareil est lent à la prise en main et peut manquer la commande serait une information précieuse. Des commentaires bien placés peuvent aider à faciliter la transition vers la compréhension du code en temps opportun.

Un code "auto-documenté" bien écrit est une joie à trouver. Un code "auto-documenté" bien écrit, avec des commentaires informatifs bien placés est une aubaine et une découverte très rare.

Juste pour donner des arguments de chaque côté de la question initiale:

Oui, le code est auto-documenté. Les variables, les méthodes et les noms de classe peuvent tous être conçus pour être faciles à lire et à comprendre, de sorte qu'il s'agit d'une forme d'auto-documentation. Il peut y avoir quelque chose dans le style de code qui donne à la fin une documentation XML qui est considérée comme une procédure standard. En d'autres termes, il appartient au développeur de fournir une documentation pouvant être mélangée avec le code.

Non, le code n'est pas auto-documenté. Les décisions commerciales prises, les choix de conception effectués et d'autres facteurs n'apparaîtront pas dans les lignes de code et devraient être notés en dehors de la base de code. Une documentation externe est donc nécessaire et ce sont des exemples.

Point de demande: donneriez-vous une réponse partielle reconnaissant les limites d'une réponse ou vous appuieriez-vous aveuglément sur le côté qui, selon vous, est la meilleure pratique? Quelle est votre conviction dans votre réponse si c'est oui ou non? Cela pourrait être perçu comme une question stressante conçue pour attirer l'attention de quelqu'un qui pourrait répondre: "Qu'est-ce que ...? C'est la question la plus stupide que vous puissiez jamais me poser. Je refuse de répondre à cela au motif qu'elle insulte mon intelligence au-delà de la croyance! " comme une réponse plutôt arrogante et pompeuse que je pouvais imaginer certaines personnes donnant une réponse avec ce ton.

De toute évidence, il était programmeur lettré dans le style de Knuth. Pour un disciple LP, le code doit être auto-documenté pour être valide. La seule réponse possible est donc "oui".

Le problème ici est qu'il n'y a pas beaucoup de langages de programmation alphabétisés et aucun que je connaisse dans une utilisation commerciale répandue. Il faudrait donc que ce soit un créneau quelque part.

Je pense que l'intervieweur aurait pu chercher: "Comment écrivez-vous le code d'auto-documentation?" avec une implicite "Quelle est votre attitude envers la documentation?"

Je suis allé à une conférence vraiment inspirante par un gars du nom de Robert C Martin une fois où il a parlé du chapitre «méthodes d'écriture» de son livre Clean Code.

Il présentait évidemment un peu la position d'un puriste, mais j'ai pris en compte son conseil que lorsque vous découpez votre code en petites méthodes réutilisables et utilisez des astuces simples comme:

• Conserver toutes les instructions dans une méthode au même niveau d'abstraction
• Extraire le contenu des conditions de flux de contrôle ou des blocs de boucle dans les appels de méthode
• Lorsque vous vous retrouvez à passer les mêmes paramètres dans plusieurs méthodes dans une classe, séparez une nouvelle classe
• Et des astuces simples comme le remplacement d'expressions booléennes cryptiques par des appels de méthode
• etc...

Vous vous retrouvez avec un code lisible et quelque peu auto-documenté (tant que vous vous efforcez d'utiliser des noms concis mais descriptifs) qui sont plus faciles à comprendre et à maintenir.

J'ai trouvé ces choses vraiment utiles, mais cela nécessite une connaissance des modèles de conception pour bien fonctionner et vous devez absolument compléter l'approche avec une documentation de classe et de méthode de haut niveau.

Habituellement, le code auto-documenté fait référence à la pratique consistant à utiliser une convention de dénomination pour les variables, les fonctions, etc., de telle sorte que le but du code est évident. Ainsi, aucun code en soi n'est pas auto-documenté. Je ne comprends pas de quoi vous parlez au troisième paragraphe. Cela semble n'avoir rien à voir avec le code auto-documenté.

Jack Reeves a fait valoir de façon convaincante que le code est une conception . Pour beaucoup, le code réel est le seul "document" qui vous indique ce que fait le système. Tout le reste se désintègre alors qu'un système vivant a tendance à s'éloigner de plus en plus du système conçu. Même si vous deviez générer un document à partir du code (comme de nombreux outils UML peuvent le faire de nos jours), ce n'est encore qu'une documentation précise du système à ce moment-là .

Donc, oui, le code est auto-documenté. La qualité de la documentation est une autre question globale.

Au fur et à mesure que je suis devenu plus expérimenté, j'ai appris que la vraie réponse est que le code et l'environnement du lecteur déterminent le niveau d'auto-documentation.

Afin de minimiser l'écart entre l'environnement du lecteur et l'environnement de l'auteur, nous ajoutons des commentaires. Plus il faut de commentaires, généralement moins l'auteur est expérimenté. Il y a un essai assez merveilleux qui décrit cet aspect du développement logiciel, mais je ne me souviens pas qui l'a écrit ou où je l'ai trouvé.

Je sais que la plupart des gens s'attendent à ce que cette question soit «non», mais je vais dire oui. Si on me le demandait dans une interview pour un emploi, je dirais quand même oui.

J'ai travaillé sur de nombreux projets différents avec des sources ouvertes et fermées. Ils ont varié dans la documentation, des simples commentaires laissés sous forme de notes du programmeur aux documentations complètes de l'API. Bien que la documentation de l'API puisse être excellente, j'ai toujours finalement atteint une situation où la documentation en langage écrit était insuffisante pour déterminer le comportement réel du code. J'ai fini par regarder le code source, faire de l'ingénierie inverse des applications ou harceler les développeurs avec un accès source pour regarder le code source et préciser davantage.

Pour moi, le code est la documentation ultime. Peu importe combien vous écrivez en mots ce qu'un programme va faire, le comportement exact est défini par le code.

Je suis d'accord que lorsque vous écrivez du code, vous devriez essayer de rendre votre code aussi descriptif que possible. Cependant, comme d'autres l'ont mentionné, il est presque impossible dans un programme complexe de décrire complètement tout ce que fait le code. Je ne suis pas contre les commentaires, en fait je trouve qu'avec de bons commentaires, il peut être plus facile de lire le code, même si le code pourrait s'expliquer sans que les commentaires lisant l'anglais ou une langue parlée soient presque toujours plus faciles.

J'ai trouvé que la documentation la plus utile n'est presque jamais un commentaire. La plupart des projets sur lesquels j'ai travaillé récemment ont inclus des wiki qui incluent toutes les différentes parties, comment ils se connectent. J'essaie d'expliquer ce que je pensais quand j'écrivais le code pour que les autres ne le cassent pas parce qu'ils ne comprenaient pas pourquoi. Cela peut également aider quelqu'un d'autre à refactoriser le code avec plus de confiance. Je me retrouve souvent hésitant à refactoriser le code car je ne sais jamais ce qu'il pourrait casser et il n'y a aucune explication. Même si vous êtes la seule personne à travailler sur un projet que je garantis dans un an ou deux, vous oublierez pourquoi vous avez fait quelque chose, même si c'est le plus beau morceau de code, vous pouvez toujours oublier pourquoi il est là.

Bien sûr, si vous avez un temps illimité. J'ai passé plus de 25 ans à documenter du code pour d'autres développeurs. Ma position a toujours été que j'essaie d'expliquer quelque chose pour qu'un autre développeur puisse le comprendre en 5 minutes, alors qu'il pouvait simplement examiner le code et le comprendre en une demi-heure. Si je sauve tous ceux qui regardent cette méthode 25 minutes, alors j'ai fait mon travail.

Je pense que le diagramme de classe devrait toujours être utilisé pour documenter le code. Je ne pense pas que si vous regardez directement le code, vous pouvez voir l'architecture complète. Je conviens que si vous avez écrit le code vous-même ou que vous y travaillez depuis longtemps, vous pouvez comprendre, mais chaque fois qu'une nouvelle demande survient chaque fois que vous devez consulter le code et rechercher où ajouter ce nouveau code.

Ce que nous faisons dans notre entreprise, c'est d'avoir des vues de diagrammes de classes de notre projet. Nous ne passons pas vraiment de temps à modéliser mais utilisons uniquement le diagramme de classes pour visualiser le code après une rétro-ingénierie. Si le code change, il existe un mécanisme de fusion et mes diagrammes de classes sont toujours mis à jour.

Ce qui est fantastique, c'est de pouvoir ajouter des commentaires, des contraintes dans le diagramme en plus de java doc. Nous inversons le projet, puis créons un modèle et finissons par extraire des vues du modèle affiché sous forme de diagrammes de classes UML. Je ne code pas à ce stade, mais j'obtiens une impression bleue de l'architecture de code et je travaille dessus pour créer ou étendre mon architecture actuelle. Si je l'aime, j'appuie sur un bouton et mon code existant est fusionné avec mes diagrammes. Je veux dire la fusion et certainement pas la génération de code complète. Seul le delta entre le code existant et mes diagrammes est écrit, pas le code complet à chaque fois.

J'étudie depuis de nombreuses années, j'ai un master et je code toujours, mais je ne veux pas seulement être un écrivain java et j'aimerais utiliser mon cerveau un peu plus. Les vues UML me donnent ce dont j'ai besoin pour réfléchir à mon architecture, communiquer avec les autres membres de l'équipe et créer une meilleure architecture sans utiliser le développement piloté par modèle, mais uniquement le delta entre le code écrit manuellement existant et créer graphiquement des diagrammes de classes. Je crée mon architecture au niveau du code, puis je l'inverse et regarde le modèle. Je crée des vues et j'essaye d'améliorer mon architecture directement dans le code, puis j'inverse à nouveau et je vois ce qui est fait etc ... C'est une itération permanente sans génération de code pilotée par le modèle mais synchronisation en direct ou fusion entre code et UML. Ce que j'aime, c'est que le code pilote l'UML et certainement pas le contraire.