Mettre des commentaires dans le code: le bon, le mauvais et le laid.

Arrêtez-moi si vous avez déjà entendu celui-ci…

«Un bon code est auto-documenté.»

En plus de 20 ans d'écriture de code pour gagner ma vie, c'est la phrase que j'ai le plus entendue.

C'est un cliché.

Et comme beaucoup de clichés, il a un noyau de vérité. Mais cette vérité a été tellement abusée que la plupart des gens qui prononcent la phrase n'ont aucune idée de ce que cela signifie vraiment.

Est-ce vrai? Oui .

Cela signifie-t-il que vous ne devriez jamais commenter votre code? Non .

Dans cet article, nous examinerons le bon, le mauvais et le laid lorsqu'il s'agit de commenter votre code.

Pour commencer, il existe en réalité deux types de commentaires de code différents. Je les appelle commentaires de documentation et commentaires de clarification .

Commentaires sur la documentation

Les commentaires de documentation sont destinés à toute personne susceptible de consommer votre code source, mais non susceptible de le lire. Si vous créez une bibliothèque ou un framework que d'autres développeurs utiliseront, vous avez besoin d'une forme de documentation API.

Plus la documentation de votre API est retirée du code source, plus elle est susceptible de devenir obsolète ou inexacte au fil du temps. Une bonne stratégie pour atténuer ce problème consiste à intégrer la documentation directement dans le code, puis à utiliser un outil pour l'extraire.

Voici un exemple de commentaire de documentation d'une bibliothèque JavaScript populaire appelée Lodash.

Si vous comparez ces commentaires à leur documentation en ligne, vous verrez qu'il s'agit d'une correspondance exacte.

Si vous écrivez des commentaires de documentation, vous devez vous assurer qu'ils suivent une norme cohérente et qu'ils se distinguent facilement de tout commentaire de clarification en ligne que vous voudrez peut-être également ajouter. Certains standards et outils populaires et bien pris en charge incluent JSDoc pour JavaScript, DocFx pour dotNet et JavaDoc pour Java.

L'inconvénient de ces types de commentaires est qu'ils peuvent rendre votre code très «bruyant» et plus difficile à lire pour quiconque est activement impliqué dans sa maintenance. La bonne nouvelle est que la plupart des éditeurs de code supportent le «pliage de code» qui nous permet de réduire les commentaires afin que nous puissions nous concentrer sur le code.

Commentaires de clarification

Les commentaires de clarification sont destinés à toute personne (y compris votre futur moi) qui pourrait avoir besoin de maintenir, de refactoriser ou d'étendre votre code.

Souvent, un commentaire de clarification est une odeur de code. Cela vous indique que votre code est trop complexe. Vous devez vous efforcer de supprimer les commentaires de clarification et de simplifier le code à la place, car «un bon code est auto-documenté».

Voici un exemple de commentaire de clarification mauvais - bien que très divertissant.

/* * Replaces with spaces * the braces in cases * where braces in places * cause stasis.**/ $str = str_replace(array("\{","\}")," ",$str);

Plutôt que de décorer une déclaration légèrement déroutante avec une rime intelligente - en dimètre amphibrach , rien de moins - l'auteur aurait été bien mieux de passer du temps sur une fonction qui rend le code lui-même plus facile à lire et à comprendre. Peut-être une fonction nommée, removeCurlyBracesappelée à partir d'une autre fonction nommée sanitizeInput?

Ne vous méprenez pas, il y a des moments - en particulier lorsque vous vous embêtez dans une charge de travail écrasante - où injecter un peu d'humour peut être bon pour l'âme. Mais lorsque vous écrivez un commentaire amusant pour compenser un mauvais code, les gens sont moins susceptibles de refactoriser et de corriger le code plus tard.

Voulez-vous vraiment être le responsable de priver tous les futurs codeurs de la joie de lire cette petite comptine intelligente? La plupart des codeurs riaient et passaient à autre chose, ignorant l'odeur du code.

Il y a aussi des moments où vous rencontrez un commentaire qui est redondant. Si le code est déjà simple et évident, il n'est pas nécessaire d'ajouter un commentaire.

Comme, ne faites pas ce non-sens:

/*set the value of the age integer to 32*/int age = 32;

Pourtant, il y a des moments où peu importe ce que vous faites au code lui-même, un commentaire de clarification est toujours justifié.

Cela se produit généralement lorsque vous devez ajouter du contexte à une solution non intuitive.

Voici un bon exemple de Lodash:

function addSetEntry(set, value) { /* Don't return `set.add` because it's not chainable in IE 11. */ set.add(value); return set; }

Il y a aussi des moments où - après beaucoup de réflexion et d'expérimentation - il s'avère que la solution apparemment naïve à un problème est en fait la meilleure. Dans ces scénarios, il est presque inévitable qu'un autre codeur arrive en pensant qu'il est beaucoup plus intelligent que vous et commence à jouer avec le code, pour découvrir que votre chemin était le meilleur depuis le début.

Parfois, cet autre codeur est votre futur moi.

Dans ces cas, il est préférable de sauver tout le monde du temps et de l'embarras et de laisser un commentaire.

Le commentaire simulé suivant capture parfaitement ce scénario:

/**Dear maintainer: Once you are done trying to 'optimize' this routine,and have realized what a terrible mistake that was,please increment the following counter as a warningto the next guy: total_hours_wasted_here = 42**/

Encore une fois, ce qui précède est plus drôle que utile. Mais vous DEVRIEZ laisser un commentaire avertissant les autres de ne pas rechercher une «meilleure solution» apparemment évidente, si vous l'avez déjà essayée et rejetée. Et lorsque vous le faites, le commentaire doit préciser quelle solution vous avez essayée et pourquoi vous avez décidé de ne pas la faire.

Voici un exemple simple en JavaScript:

/* don't use the global isFinite() because it returns true for null values*/Number.isFinite(value)

Le moche

Donc, nous avons examiné le bon et le mauvais, mais qu'en est-il du laid?

Malheureusement, il y a des moments dans n'importe quel travail où vous vous sentez frustré et lorsque vous écrivez du code pour gagner votre vie, il peut être tentant d'exprimer cette frustration dans les commentaires de code.

Travaillez avec suffisamment de bases de code et vous rencontrerez des commentaires allant du cynique et déprimant au sombre et méchant.

Des choses comme les apparemment inoffensives…

/*This code sucks, you know it and I know it. Move on and call me an idiot later.*/

… Au vrai sens

/* Class used to workaround Richard being a f***ing idiot*/

These things may seem funny or may help release a bit of frustration in the moment, but when they make it into production code they end up making the coder who wrote them and their employer look unprofessional and bitter.

Don't do this.

If you enjoyed this article, please smash the applause icon a bunch of times to help spread the word. And if you want to read more stuff like this, please sign up for my weekly Dev Mastery newsletter below.