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 says3* captcha is optional for this API version4* @see https://developers.scalefast.com/docs/sign-up-sign-in5**/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 #135742abstract 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.
A lire
Autres articles de la même catégorie
Au-delà du MVC
Réfléchissons à notre relation envers les frameworks et au choix d'architecture qui en découle.
Mathieu De Gracia
Vous avez le droit de commenter
Et si parfois on s'autorisait à commenter notre code ?
Mathieu De Gracia
Comité Refactorisation : Améliorer le code existant
Résorbez progressivement la dette technique de votre application grâce à un comité de refactorisation
Mathieu De Gracia