Les commentaires dans le code

J'ai lu une partie du livre Coder Proprement de Robert C. Martin. L'auteur nous donne de très nombreuses astuces et règles à suivre pour arriver à un code facilement maintenable et compréhensible. La grande majorité de ces conseils est tout à fait correcte et logique. Robert C. Martin a réellement fait un gros travail tiré de son expérience pour essayer de proposer un ensemble de règles visant à avoir un code propre.
Mais concernant les commentaires je ne suis pas d'accord avec l'auteur. Voici, en résumé ce qu'il dit des commentaires :

  1. Les commentaires sont utiles uniquement lorsque le code ne peut pas expliquer ce qui se passe.
  2. Les commentaires doivent être évités au profit de fonctions dont le nom correspondra à l'explication du code.
  3. Les commentaires vieillissent s'ils ne sont pas maintenus ce qui rend leur utilisation dangereuse.

Je suis d'accord avec les points 1 et 3, quoi que je relativise un peu le 3.
Concernant le point 1 : Je suis d'accord sur le fait que dans le code suivant (légèrement exagéré) les commentaires sont redondants, superflus et qu'ils alourdissent la lecture du code ainsi que sa maintenance.

# On ajoute un nouvel élève à partir des données du formulaire
new_eleve = Eleve(nom=form.nom, prenom=form.prenom)
# On valide l'inscription du nouvel élève
new_eleve.inscription_valide = True
# On définit le prof connecté comme le prof de l'élève
new_eleve.prof = request.user
# On sauvegarde le nouvel élève
new_eleve.save()

Concernant le point 3, je pense que les développeurs doivent rester cohérents avec ce qu'ils font. C'est surement dû au fait que j'ai une vision Pythonique du développement, mais un développeur qui modifie un code doit prendre en compte les commentaires. Comme il doit prendre en compte les futures personnes qui maintiendront son code. Par exemple, un commentaire qui correspond à un bloc de code doit se trouver le plus proche possible de ce code et dans le même bloc (bloc séparé par une ligne vide pas bloc d'accolades). Plus un commentaire sera loin de son code ou sera général, moins il sera mis à jour.

En revanche concernant le point 2 qui spécifie "Les commentaires doivent être évités au profit de fonctions dont le nom correspondra à l'explication du code", je ne suis pas d'accord. D'un point de vue lecture superficielle du code, oui c'est une bonne idée. En revanche, pour rechercher l'origine d'un bug, lorsque le développeur déroule la liste du code exécuté il devient très laborieux de naviguer dans le code.
Le développeur se retrouve à devoir voir le code de chacune des fonctions s'il veut comprendre l'intégralité du code.
Dans mon exemple d'enregistrement de l'élève, si le code de la view (contrôleur dans MVC) est très important j'aurais tendance à passer par une méthode pour décharger la view et probablement mutualiser du code. Mais si le code de la view n'est pas très volumineux et que le code à expliquer ne sera pas réutilisé je préfère utiliser un commentaire.
Exemple de cas où le commentaire peut expliquer un bloc et où la lisibilité est bonne :

   if form.is_valid():

# Ajout de l'élève
new_eleve = Eleve(nom=form.nom, prenom=form.nom)
new_eleve.inscription_valide = True
new_eleve.prof = request.user
new_eleve.save()

# Intégration du livret scolaire de l'élève
new_livret = Livret(eleve=new_eleve)
...

 Je trouve ce code lisible, explicite et moins compliqué à lire dans le détail que si on avait eu des méthodes. Bien évidemment, le principe du DRY supplante tous les autres principes (Enfin sauf si votre vie en dépend). Pour ne pas paraître trop extrême, il arrive des où dupliquer le code éviter de le complexifier et donc où il convient mieux de le dupliquer.

Commentaires métier

Étant donné qu'on parle de commentaire je voulais également rajouter qu'il peut être utile de rajouter des commentaires métiers. Lorsqu'on effectue un test qui n'est pas purement procédural ou explicite il convient de rajouter un commentaire en expliquant ce qu'on fait et la règle métier (simplifiée, pas la peine de rajouter un pavé énorme).

Si un code contient énormément de règles métier ou que ces règles sont amenées à être modifiée régulièrement, il peut être utile d'ajouter un commentaire en début de fichier, en début de classe ou de méthode pour diriger le développeur vers un doc qui liste les règles métiers. Il faut faire ça pour deux raisons :

Du code en commentaire

D'une manière générale, mettre du code en commentaire est à éviter au maximum. Pourquoi ?
Parce que bien souvent, on met du code en commentaire en se disant "Ca peut-être utile. On ne sait jamais." On peut aussi le mettre en commentaire pour le sauvegarder ou ne pas le perdre, mais ce travail c'est celui du gestionnaire de version si le code a déjà été commité. Il faut une vraie bonne raison de mettre des codes en commentaires !

Commentaire pour un code abscon

Robert C. Martin explique qu'un commentaire qui explique un code mal conçu ne devrait pas exister, le développeur devrait refactoriser le code pour que celui-ci soit compréhensible sans commentaire. Effectivement, c'est ce qu'il y a de mieux à faire dans un monde où il n'y a aucun délai. Dans les 3 entreprises dans lesquelles j'ai été développeur, j'ai travaillé sur des applications existant depuis au moins une décennie. Sur de telles applications, si un champ en base de données a mal été nommé dès le début, il est impensable de vouloir le changer 10 ans après lorsque ce champ est utilisé partout. S’il y a une portion de code qu'on ne peut pas refactoriser rapidement et qu'on a passé plusieurs minutes voire plusieurs heures, il peut être utile de rajouter un commentaire pour que le prochain développeur ne perde pas son temps.

Voilà ce que je m'applique comme règle concernant les commentaires pour mon travail perso. En tant que salarié, je me calque souvent sur le code existant (Plus ou moins facilement selon le code), pour garder un code homogène et simplifier la lecture des autres intervenants.