Si tu as lu mon article sur le Comment Driven Refactoring, tu sais qu'un code clean doit pouvoir se passer de commentaires. Il doit se lire facilement et naturellement.
Sauf que ça n'est pas toujours possible !
Le langage de programmation que tu utilises n'est pas parfait. Il ne te permet pas d'exprimer tout ce que tu veux, comme tu le veux.
Dans ces cas-là, ajouter le bon commentaire au bon endroit est peut-être la meilleure solution.
Eh oui, tout comme il y a des bons et des mauvais chasseurs (t'as la réf ? 😉), il y a des bons et des mauvais commentaires.
Il est temps de parler des bons commentaires : ceux qui améliorent le code dans lequel ils se trouvent !
Le code de base
Observons cette ligne de code, écrite en PHP :
$date = new DateTime('midnight, first day of');
On y instancie un objet DateTime.
Mais à quelle date, exactement ? Que dit le code ?
Nouvelle date : minuit, premier jour de.
Le premier jour de ? Le premier jour de quoi ? Il ne manque pas un bout, là ?
- Le premier jour de l'année, le 1er Janvier ?
- Le premier jour de la semaine actuelle, donc lundi ?
A moins de connaître la documentation [1] par coeur, on ne peut qu'essayer de deviner.
Le commentaire
C'est là que le commentaire dont je vais te parler entre en jeu.
Il n'est pas très long : juste deux mots. Mais c'est largement suffisant pour donner tout son sens au code.
Tu es prêt à poser tes yeux sur cette merveille ? La voilà :
$date = new DateTime('midnight, first day of' /* current month */);
Nouvelle date : minuit, premier jour du mois en cours.
C'était donc ça, on parlait du mois actuel !
C'est quand même plus compréhensible quand le commentaire nous explique tout, tu ne trouves pas ?
Plus besoin de lire la doc, car le code se lit comme de la prose. On peut même le lire à haute voix et il garde tout son sens !
C'est beau !
Les explications
Pourquoi le code parle du mois en cours ?
Tu as déjà remarqué que quand on crée un objet DateTime sans lui donner de paramètres, on obtient la date actuelle ?
$date = new DateTime(); // => date et heure de maintenant
C'est parce que la valeur par défaut passée au constructeur de DateTime, c'est now. Cela correspond à la date actuelle, y compris le mois.
De la même manière, quand on spécifie une valeur au constructeur, toutes les données que l'on n'indique pas (mois, jour, heures, secondes ...) seront remplacées par la valeur par défaut : celle de maintenant.
C'est ce qu'il se passe dans notre code. On ne précise pas le mois souhaité, juste l'heure et le jour, donc PHP va utiliser le mois en cours (ainsi que l'année).
Depuis tout ce temps, on utilisait now sans le savoir, car il était présent de manière implicite !
Sans commentaires
Il existe une version de ce code qui ne nécessite pas de commentaires.
Pour cela, on va expliciter la valeur par défaut (now). Voyons ce que ça donne :
$date = new DateTime('midnight, first day of now');
Nouvelle date : minuit, premier jour de maintenant.
On comprend un peu mieux.
Mais est-ce que cette version est meilleure que celle avec un commentaire ? Je ne pense pas.
Deux choses me dérangent :
1. Ca sonne moins bien
"Le premier jour de maintenant", c'est pas très bien dit. "Le premier jour du mois en cours", c'est beaucoup plus clair.
Quand on lit now, on doit se rappeler qu'on ne parle pas de "maintenant", mais du "mois de maintenant". C'est comme si on avait écrit first day of "now's month" ... sauf qu'on ne l'a pas écrit.
Ici encore, il faut connaître la doc pour être sûr de savoir ce que le code va faire.
La version avec un commentaire nous facilite donc la lecture.
2. La doc a dit non
La documentation PHP [1] nous recommande la chose suivante :
'first day of' [...] Il est plus intéressant d'utiliser cette phrase suivie d'un nom de mois.
Même la documentation officielle dit que si on n'indique pas le mois, ça risque d'être moche.
Or, now ne désigne pas un mois. En tout cas, pas directement. Cela désigne un instant bien précis, qui lui-même possède un mois. C'est pas la même chose.
En revanche, en écrivant current month, on désigne directement un mois bien défini. Et c'est exactement ce que la doc nous conseille de faire !
La version avec un commentaire est donc plus respectueuse des recommandations.
Conclusions
- Les langages de programmation ne nous permettent par d'écrire du code 100% clean.
- Parfois, un commentaire vaut mieux que du code natif.
- On garde le commentaire ? 😊