Les meilleurs commentaires sont ceux que l’on n’a pas besoin d’écrire.
Lorsque l’on a besoin d’écrire un commentaire, le plus souvent, c’est que notre code n’est pas aussi clair et propre qu’il devrait l’être.
Je suis bien d’accord avec la citation du dessus, mais elle n’implique aucunement ce qui suit.
Damned, un développeur faisant une telle faute logique ? On devrait savoir que les relations de cause et conséquence ne s’inversent pas. Si les meilleurs commentaires sont ceux qu’on n’a pas besoin d’écrire, personne n’a dit qu’on ne devrait pas écrire les commentaires !
function main() {
let imageName = 'test.png'
let pieces = imageName.split('.')
let extension = pieces.pop()
}
[…] ça ressemble beaucoup trop à une excuse : « Mon code est moche / compliqué mais c’est pas grave je vais l’expliquer dans un commentaire » au lieu de le nettoyer.
Donc oui, ce commentaire est à peu près inutile. S’il le devient c’est que le code est probablement inutilement complexe et pourrait être améliorer avec l’utilisation de fonctions tierces bien nommées.
Si effectivement vous commentez ainsi (pas de honte, ça arrive à tous), ça ne sert à rien.
Par contre, un commentaire qui dit pourquoi vous avez besoin de l’extension ça ne serait pas forcément du luxe. Peut-être que ce commentaire manquant me permettrait de savoir si le comportement face à un fichier « .test.png » est une anomalie ou est volontaire. Là je suis bien à mal de savoir sans lire tout le code source en détail pour chercher l’intention du développeur.
Bref, si vous croyez qu’un code source clair remplace les commentaires, c’est que vous n’avez pas encore compris ce qu’il faut écrire dans les commentaires.
function getFileExtension(filename) {
let pieces = imageName.split('.')
return pieces.pop()
}
Dites moi qu’il y a une information dans ce commentaire que vous n’aviez pas en lisant le code !
Non. Par contre dans un IDE évolué, ce type de code me permet d’avoir confirmation du rôle de la fonction quand je la tape ou quand je la lis plutôt que de devoir m’interrompre pour aller ouvrir le fichier correspondant et lire tout le code source. D’autant 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 commentaires de @ que l’IDE me donnera le rôle des différents paramètres. Oui, le plus souvent ils devraient être évident mais est-ce toujours le cas ? Grâce à ce jsdoc je saurais sans ouvrir la fonction que je dois y renseigner 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écution de mon programme. Je saurai aussi si j’ai ou pas un argument optionnel et pourquoi.
Toujours avec un outillage évolué, la mention du string permettra d’identifier des erreurs de typage malencontreuses. Ça pourrait être dans le prototype de la fonction avec flow ou ici dans le commentaire, peu importe, seule la syntaxe diffère.
Maintenant même ici, le problème n’est pas avec le commentaire mais avec ce qu’il dit. Ça n’aurait pas été du luxe que la fonction décrive que ce qu’elle considère être une extension dans le cas d’un « test.tar.gz ».
Là où le code est propre le commentaires ne sera qu’une redondance sans grand intérêt que le cerveau apprendra vite à ignorer.
Et si c’était le contenu des commentaires qu’il fallait remettre en cause et pas leur présence ?
Sinon oui, je règle mes outils pour que les commentaires s’affichent 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 fonction (et là je veux ignorer les commentaires) ou que je l’étudie la première fois.
Le seul problème que je rencontre aujourd’hui se produit dans le cadre de project avec une documentation publique auto-générée. Comment éviter la redondance tout en faisant en sorte que la documentation générée à partir de mes commentaires soit complète.
Si la documentation générée pour les développeurs a besoin des commentaires, c’est que peut-être l’assertion comme quoi le code est aussi simple et efficace à lire que les commentaires… est peut-être fausse. Je dis ça je dis rien.
