1. Comment... or not comment

Par Pascal Le Merrer (@pascallemerrer)

1.1. Pourquoi commenter

Faciliter la lecture du code par le lecteur
"Code never lies, documentations sometimes does", Ron Jeffries
"Writing system software: code comment", Salvatore Sanfilippo ( @antirez ), développeur chez Redis
- Salvatore Sanfilippo définit 6 types de commentaires utiles et 3 inutiles

Commentaire de fonction
- Une majorité des personnes présentes commentent leurs fonctions
- Le speaker considère que cela n'est pas toujours nécessaire, le nom de la fonction est la plupart du temps largement suffisant
Commentaire de conception
- Explique les solutions envisagées et celles retenues et pourquoi
Commentaire de raison
- Explique pourquoi cette fonction fait cela ( pas "comment ?" mais bien "pourquoi ?" )
Commentaire d'enseignement
- Donne les bases théoriques nécessaires à la compréhension de ce que fait le code
  - Rappelle des bases de géométries pour des fonctions de géolocalisation par exemple
  - Une minorité des personnes est d'accord
  - La majorité pense qu'un lien vers une doc suffit
Commentaire de checklist
- Prévient le prochain développeur des différentes étapes à suivre en cas de modifications sur la fonction courante
  - Peut faire penser à un problème de conception si il est nécessaire de faire ce genre de choses
Commentaire de guidage
- Chaque section du code est précédée par un petit commentaire pour expliquer ce qui va se passer
- Le speaker est contre ce genre de choses, il préfère faire des sous-fonctions avec des noms équivoques

Commentaire trivial
- Les commentaires plus long à lire qu'à lire le code
Commentaire de dettes techniques
- TODO, FIXME, etc...
  - Le speaker n'est pas contre, à condition qu'on prenne le temps, ultérieurement, de vraiment le faire
- Commentaire pour prévenir qu'il s'agit d'un hack
Commentaire de sauvegarde
- Commenter du code au cas où on pourrait en avoir besoin plus tard
  - Il suffit d'utiliser le système de versioning...