La citation de Robert C. Martin est sortie de son contexte. Voici la citation avec un peu plus de contexte:
Rien ne peut être aussi utile qu'un commentaire bien placé. Rien ne peut encombrer un module plus que des commentaires dogmatiques frivoles. Rien ne peut être aussi préjudiciable qu’un vieux commentaire cruel qui propage des mensonges et de la désinformation.
Les commentaires ne ressemblent pas à la liste de Schindler. Ils ne sont pas "pur bien". En effet, les commentaires sont, au mieux, un mal nécessaire. Si nos langages de programmation étaient suffisamment expressifs, ou si nous avions le talent de les utiliser subtilement pour exprimer notre intention, nous n'aurions pas beaucoup besoin de commentaires - peut-être même pas du tout.
L'utilisation appropriée des commentaires doit compenser notre incapacité à nous exprimer en code. Notez que j'ai utilisé le mot échec. C'est ce que je voulais dire. Les commentaires sont toujours des échecs. Nous devons les avoir car nous ne pouvons pas toujours comprendre comment nous exprimer sans eux, mais leur utilisation n’est pas un motif de célébration.
Ainsi, lorsque vous vous trouvez dans une position où vous devez écrire un commentaire, réfléchissez-y et voyez s'il n'y a pas de moyen de renverser la situation et de vous exprimer en code. Chaque fois que vous vous exprimez en code, vous devriez vous féliciter. Chaque fois que vous écrivez un commentaire, vous devriez faire la grimace et ressentir l’échec de votre capacité d’expression.
(Copié à partir d'ici , mais la citation originale provient de Clean Code: Un manuel de l'artisanat logiciel agile )
Comment cette citation est réduite à "Les commentaires sont toujours des échecs" est un bon exemple de la façon dont certaines personnes vont prendre une citation raisonnable hors de son contexte et la transformer en dogme stupide.
La documentation de l'API (comme javadoc) est censée documenter l'API afin que l'utilisateur puisse l'utiliser sans avoir à lire le code source . Donc, dans ce cas, la documentation devrait expliquer ce que fait la méthode. Vous pouvez maintenant affirmer que "Récupérer un produit par son identifiant" est redondant car il est déjà indiqué par le nom de la méthode, mais les informations null
pouvant être renvoyées sont définitivement importantes pour la documentation, car elles ne sont en aucun cas évidentes.
Si vous souhaitez éviter la nécessité du commentaire, vous devez supprimer le problème sous-jacent (l'utilisation de null
comme valeur de retour valide) en rendant l'API plus explicite. Par exemple, vous pouvez renvoyer un type de Option<Product>
type, de sorte que la signature de type elle-même communique clairement ce qui sera renvoyé au cas où le produit ne serait pas trouvé.
Toutefois, dans tous les cas, il n'est pas réaliste de documenter une API de manière complète uniquement par le biais de noms de méthodes et de signatures de types. Utilisez doc-comments pour toute information supplémentaire non évidente que l'utilisateur devrait connaître. Prenez par exemple la documentation de l'API DateTime.AddMonths()
dans la BCL:
La méthode AddMonths calcule le mois et l'année obtenus en tenant compte des années bissextiles et du nombre de jours d'un mois, puis ajuste la partie jour de l'objet DateTime obtenu. Si le jour résultant n'est pas un jour valide du mois résultant, le dernier jour valide du mois résultant est utilisé. Par exemple, 31 mars + 1 mois = 30 avril. La partie heure de l'objet DateTime résultant reste la même que cette instance.
Il est impossible d'exprimer cela en utilisant uniquement le nom de la méthode et sa signature! Bien entendu, la documentation de votre classe n’exigera peut-être pas ce niveau de détail, ce n’est qu’un exemple.
Les commentaires en ligne ne sont pas mauvais non plus.
Les mauvais commentaires sont mauvais. Par exemple, des commentaires qui n'expliquent que ce que l'on peut déduire du code, l'exemple classique étant:
// increment x by one
x++;
Les commentaires qui expliquent quelque chose qui pourrait être clarifié en renommant une variable ou une méthode ou en restructurant le code, constituent une odeur de code:
// data1 is the collection of tasks which failed during execution
var data1 = getData1();
C’est le genre de commentaires que Martin a critiqués. Le commentaire est le symptôme d'une incapacité à écrire du code clair - dans ce cas, utiliser des noms explicites pour les variables et les méthodes. Le commentaire lui-même n’est bien sûr pas le problème, c’est que nous avons besoin du commentaire pour comprendre le code.
Mais les commentaires doivent être utilisés pour expliquer tout ce qui n’est pas évident dans le code, par exemple pourquoi le code est écrit d’une certaine manière non évidente:
// need to reset foo before calling bar due to a bug in the foo component.
foo.reset()
foo.bar();
Les commentaires qui expliquent ce qu'une partie de code trop compliquée fait aussi, c'est une odeur, mais le correctif n'est pas d'interdire les commentaires, le correctif est le correctif du code! Dans le vrai mot, le code compliqué arrive (espérons-le seulement temporairement jusqu'à ce qu'un refactor), mais aucun développeur ordinaire n'écrit du code parfaitement propre la première fois. Lorsque du code compliqué arrive, il est bien mieux d'écrire un commentaire expliquant ce qu'il fait que de ne pas écrire un commentaire. Ce commentaire facilitera également la refactorisation ultérieure.
Parfois, le code est inévitablement complexe. Il peut s’agir d’un algorithme compliqué ou d’un code qui sacrifie la clarté pour des raisons de performances. Encore une fois, les commentaires sont nécessaires.