Vous avez le droit de commenter

L'informatique est gangrénée par les dictons.

Ces dictons que l'on assène comme des sentences au détour d'une code reviews : "dont repeat yourself", "ne pas déployer un vendredi", "ne commentez pas votre code"

Un dicton est rassurant... et puis ils partent tous d'une bonne intention, mais sont-ils tacitement pertinents dans toutes les situations ?

Une petite duplication de code sans logique métier est-elle vraiment préjudiciable pour votre application ? Probablement que non, une factorisation trop prématurée a cependant toutes ses chances de l'être.

Nous nous réfugions derrière ces phrases toutes faites sans chercher à les comprendre mais comment appliquer judicieusement une règle que l'on ne comprend dans le fond pas vraiment.

Un professionnel ne se contente pas de suivre les conventions, il y ajoute de la nuance.

Ouvrage de référence quand il s'agit de qualité logicielle, le clean coder de Robert C. Martin (aka Uncle Bob) décrit 6 types de commentaires différents, pensez-vous réellement que ces 6 types peuvent être résumés à une simple maxime réductrice : "ne commentez pas" ?

Pendant quelques minutes, soyons de véritables artisans et prenons du recul sur nos pratiques.

Le mauvais commentaire

Rien n'encombre autant que des commentaires sans importance ~ Uncle Bob

Mettons quelque chose au clair tout de suite : un commentaire est dangereux.

Il émane bien souvent d'un code trop complexe ou peu expressif que l'on cherche à clarifier à l'aide d'un commentaire, le commentaire devient alors une rustine malencontreuse à un problème plus général.

Il est également très difficile, voire impossible, à maintenir dans le temps.

Un commentaire ment ou mentira un jour ou l'autre et ce mensonge pourrait être encore plus préjudiciable et induire en erreur que l'absence même de commentaire.

Cependant, il existe quelques situations ou un commentaire est justifiable.

Le bon commentaire

Rien n'est plus utile qu'un commentaire bien placé ~ Uncle Bob

Pourquoi écrivons-nous des commentaires ? Pour combler un manque, une incompréhension, que le code seul ne peut fournir.

Le code consiste en une longue liste d’instructions possédant sa propre grammaire et, par moments, cette grammaire sera insuffisante pour décrire précisément un choix de design.

Pourquoi avoir utilisé Carbon plutôt qu'un Datetime ou même un now() dans le cadre de Laravel ? Ce choix peut paraître anodin mais avait-il une importance ? Quelles contraintes techniques justifiaient ce choix ?

Le code est tout bonnement incapable d'expliquer clairement et succinctement les intentions car ce n'est pas son rôle premier !

Un commentaire informatif amenant à une documentation plus complète sera alors salvateur et parfaitement justifié.

1/**
2* Warning, despite what the documentation says
3* captcha is optional for this API version
4* @see https://developers.scalefast.com/docs/sign-up-sign-in
5**/
6$response = Http::post('https://api.scalefast.com/oauth');

Un commentaire sera donc un choix envisageable quand il répondra à une contrainte qui ne provient pas du code en lui-même mais de son implémentation.

Le commentaire aura cependant ses propres limites et il sera toujours préférable de faire référence à une documentation externe qui sera bien plus complète, versionnée, et maintenue indépendamment du code.

1# Do not add new "STATUS_" const. See issue #13574
2abstract class UserConstants {

It's a long way

Pendant longtemps j'y ai cru, je l'avoue.

Pour moi écrire un commentaire était un signe d'échec, la conséquence d'une simplicité que je n'arrivais pas à coder. Ce sentiment d'échec est certes toujours présent mais le réalisme a pris le pas sur la honte.

Plongez quelques minutes dans les entrailles de votre framework préféré, Symfony, Laravel, et vous y trouverez multitude de commentaires au détour d'une fonctionnalité complexe. Est-ce du mauvais code pour autant ?

Parfois l'expressivité confronte la performance.

Comprenez en quoi un commentaire est problématique et vous pourrez en écrire et vous appliquerez ce fameux dicton avec moins de maladresse.

Il y a fort longtemps dans un projet, j'ai commencé à écrire quelques #DesperateAdvice pour tenter de clarifier des comportements complexes d'un legacy.

Il est fort probable qu'une véritable documentation aurait pu compléter ces tips mais néanmoins ces quelques lignes glanées ci et là dans le code étaient salutaires.

Désormais, ces quelques tips doivent probablement être obsolètes, mais ils représentaient à un moment donné un mal nécessaire.

Est-ce que c'était parfait ? Non. Est-ce que c'était utile ? Certainement.