Les commentaires sont des promesses

En relisant du code legacy, je tombe sur cet exemple :

const maxBackupTime = 1000 * 60 * 5 // 5 minutes

Sans aucun doute et sans refaire le calcul, je comprends donc que le temps maximum de sauvegarde est de 5 minutes. Parfait, on passe à la suite.

…

Les commentaires sont des promesses.

Et les promesses n'engagent que ceux qui les écoutent, comme disait Queuille.

Alors, allons un peu plus loin et regardons comment ce code pourra évoluer dans l'avenir :

const maxBackupTime = 1000 * 60 * 60 * 5 // 5 minutes

ou encore :

const maxBackupTime = 1000 * 60 * 15 / 2 // 5 minutes

ou même :

const maxBackupTime = 600 * 5 // 5 minutes

La valeur de maxBackupTime est ce qu'on appelle un magic number. Pourquoi magique ? Parce qu'il vient de nulle part et a donc besoin d'un commentaire pour expliquer son existence.

Mais « les commentaires sont des promesses » que nous ne pouvons pas croire les yeux fermés. Et dans ce cas, il faudra du temps pour comprendre ce qu'ils voulaient dire et leur histoire et leur rapport avec le magic number.

Alors c'est vrai, à première vue, c'est lisible, on comprend tout de suite. Mais s'il mentait !

Je propose donc d'utiliser ce genre de code :

const FIVEMINUTES = 300000
const maxBackupTime = FIVEMINUTES

Ou encore plus explicite, juste pour faire râler les personnes qui aiment partager un code plus proche de la bidouille que de l'artisanat :

const MILLISECOND = 1
const SECOND = 1000 * MILLISECOND
const MINUTE = 60 * SECOND
const maxBackupTime = 5 * MINUTE

Entre les étiquettes qu'on trouve sur les boîtes dans une cuisine (riz, pâtes, lentilles, etc.), ou dans un atelier (vis, clous, écrous, etc.), les étiquettes qu'on trouve sur les sonnettes des immeubles, voire même la pancarte "peinture fraîche" sur un banc public. Je confirme :

Les commentaires sont des promesses.