Les meilleurs commen­taires ne s’écrivent pas

Les meilleurs commen­taires sont ceux que l’on n’a pas besoin d’écrire.

Lorsque l’on a besoin d’écrire un commen­taire, le plus souvent, c’est que notre code n’est pas aussi clair et propre qu’il devrait l’être.

Je suis bien d’ac­cord avec la cita­tion du dessus, mais elle n’im­plique aucu­ne­ment ce qui suit.

Damned, un déve­lop­peur faisant une telle faute logique ? On devrait savoir que les rela­tions de cause et consé­quence ne s’in­versent pas. Si les meilleurs commen­taires sont ceux qu’on n’a pas besoin d’écrire, personne n’a dit qu’on ne devrait pas écrire les commen­taires !

function main() {  
  let imageName = 'test.png'

  // Get the extension off the image filename  
  let pieces = imageName.split('.')
  let extension = pieces.pop()
}

[…] ça ressemble beau­coup trop à une excuse : « Mon code est moche / compliqué mais c’est pas grave je vais l’ex­pliquer dans un commen­taire » au lieu de le nettoyer.

Donc oui, ce commen­taire est à peu près inutile. S’il le devient c’est que le code est proba­ble­ment inuti­le­ment complexe et pour­rait être amélio­rer avec l’uti­li­sa­tion de fonc­tions tierces bien nommées.

Si effec­ti­ve­ment vous commen­tez ainsi (pas de honte, ça arrive à tous), ça ne sert à rien.

Par contre, un commen­taire qui dit pourquoi vous avez besoin de l’ex­ten­sion ça ne serait pas forcé­ment du luxe. Peut-être que ce commen­taire manquant me permet­trait de savoir si le compor­te­ment face à un fichier « .test.png » est une anoma­lie ou est volon­taire. Là je suis bien à mal de savoir sans lire tout le code source en détail pour cher­cher l’in­ten­tion du déve­lop­peur.

Bref, si vous croyez qu’un code source clair remplace les commen­taires, c’est que vous n’avez pas encore compris ce qu’il faut écrire dans les commen­taires.

/**
 * Get the extension of the file
 * 
 * @param {string} filename - The filename
 * @return {string} the extension of the file  
 */
function getFileExtension(filename) {  
  let pieces = imageName.split('.')
  return pieces.pop()
}

Dites moi qu’il y a une infor­ma­tion dans ce commen­taire que vous n’aviez pas en lisant le code !

Non. Par contre dans un IDE évolué, ce type de code me permet d’avoir confir­ma­tion du rôle de la fonc­tion quand je la tape ou quand je la lis plutôt que de devoir m’in­ter­rompre pour aller ouvrir le fichier corres­pon­dant et lire tout le code source. D’au­tant que là ce sont deux lignes mais parfois, même si c’est clair, c’est quand même plus long à lire.

C’est aussi avec les commen­taires de @ que l’IDE me donnera le rôle des diffé­rents para­mètres. Oui, le plus souvent ils devraient être évident mais est-ce toujours le cas ? Grâce à ce jsdoc je saurais sans ouvrir la fonc­tion que je dois y rensei­gner un nom de fichier et pas un chemin complet. Bien m’en a pris parce que « ./test.png » aurait provoqué de jolies erreurs à l’exé­cu­tion de mon programme. Je saurai aussi si j’ai ou pas un argu­ment option­nel et pourquoi.

Toujours avec un outillage évolué, la mention du string permet­tra d’iden­ti­fier des erreurs de typage malen­con­treuses. Ça pour­rait être dans le proto­type de la fonc­tion avec flow ou ici dans le commen­taire, peu importe, seule la syntaxe diffère.

Main­te­nant même ici, le problème n’est pas avec le commen­taire mais avec ce qu’il dit. Ça n’au­rait pas été du luxe que la fonc­tion décrive que ce qu’elle consi­dère être une exten­sion dans le cas d’un « test.tar.gz ».

Là où le code est propre le commen­taires ne sera qu’une redon­dance sans grand inté­rêt que le cerveau appren­dra vite à igno­rer.

Et si c’était le contenu des commen­taires qu’il fallait remettre en cause et pas leur présence ?

Sinon oui, je règle mes outils pour que les commen­taires s’af­fichent en gris clair. Pas qu’ils soient sans inté­rêt mais parce que j’ai deux niveaux de lecture suivant que je travaille le corps de la fonc­tion (et là je veux igno­rer les commen­taires) ou que je l’étu­die la première fois.

Le seul problème que je rencontre aujourd’­hui se produit dans le cadre de project avec une docu­men­ta­tion publique auto-géné­rée. Comment éviter la redon­dance tout en faisant en sorte que la docu­men­ta­tion géné­rée à partir de mes commen­taires soit complète.

Si la docu­men­ta­tion géné­rée pour les déve­lop­peurs a besoin des commen­taires, c’est que peut-être l’as­ser­tion comme quoi le code est aussi simple et effi­cace à lire que les commen­tai­res… est peut-être fausse. Je dis ça je dis rien.