Envoyé par
Chatanga
Pour moi, un commentaire ne doit pas décrire ce que fait un élément de code sauf si cet élément de code est mal écrit (et donc difficile à comprendre) et qu'il n'est pas possible de le réécrire. Dans ce cas là, je parle de commentaires factuels. Par exemple, quand j'ai à reprendre un code existant, j'ai l'habitude d'écrire des tas de commentaires factuels dans le code qui disparaitront au fur et à mesure du refactoring si ce dernier est envisageable. Alternativement, quand j'écris directement du code, je factorise naturellement chaque commentaire factuel en une méthode et ses paramétres en structures de données complexes (du moins quand je suis bien révéillé).
Idéalement et c'est pour moi un motif de satisfaction qu'en j'y arrive, mon code s'articule en deux étapes : construction d'une grammaire (faite de méthodes et de classes) adaptée à mon problème à l'aide des briques polyvalentes du langage et expression du problème et de sa solution dans cette grammaire. Le résultat est naturellement lisible sans nécessité d'être paraphrasé.
Donc, les commentaires factuels perdent naturellement leur utilité quand un code est bien écrit. Il existe néanmoins des commentaires pour tout le reste : souligner au lecteur certaines parties du code significatives (une section critique, une exécution couteuse en temps, une non-portabilité à envisager), détailler le contexte (à quoi servira en pratique telle donnée construite à tel endroit, la raison d'une approche plutôt qu'une autre tout aussi valide à tel autre endroit) et ainsi de suite. L'élément commun à tous ces commentaires est à mon sens l'intention pédagogique (et c'est pour ça qu'ils sont difficules à écrire pour celui qui crée un code et qui le connait intimement). Alternativement, dans le cas où seule l'interface d'une méthode est disponible, la vertue pédagogique d'un commentaire devient indispensable pour un lecteur qui n'a pas accès à son implémentation (un peu comme s'il ne savait pas en lire le langage).
Partager