Faut-il éradiquer les commentaires ?

Les arguments des deux camps sont à peu près les suivants :

Les commentaires, c'est bien :

• Un code sans commentaire est incompréhensible
• Un code est plus facile à comprendre avec des commentaires
• Les commentaires permettent d'expliquer le propos du code à un plus haut niveau d'abstraction
• Les commentaires permettent de scanner le code
• Il vaut mieux qu'il y en ait trop que pas assez
• De toutes façons, ça ne peut pas faire de mal

Les commentaires, c'est le mal absolu :

• Les commentaires servent juste à répéter le code en moins précis
• Les commentaires rajoutent de la complexité et doivent être maintenus en même temps que le code
• Mal utilisé, un commentaire complexifie la lecture plus qu'il ne la facilite
• Il vaut mieux refactoriser son code que rajouter un commentaire
• Si un développeur ne peut pas rendre son code clair, comment voulez vous qu'il écrive des commentaires clairs ?
• Je dois déjà me casser le c** à lire du code, il faudrait encore que je me coltine les commentaires ?
• Les commentaires sont une perte de ressource
• Les commentaires, c'est pour les newbies

Chacun des camps dispose d'arguments plus ou moins valables. Au delà de ces deux extrêmes, le développeur pragmatique s'attachera à comprendre à quoi servent les commentaires, pour bien les utiliser.

À quoi servent les commentaires ?

Pour mettre les pendules à l'heure, je dirai que les commentaires ne servent pas à :

• Raconter la vie du développeur : C'est marrant comme certains développeurs adorent étaler leurs états d'âmes ou raconter leur soirée dans leur code source. Finalement, un code, c'est un peu comme un journal intime. C'est plein de vie.

  Cela dit, la vie du développeur précédent n'est pas d'une grande aide quand il faut corriger ses anneries.

• Supprimer des bouts de code devenus inutiles : Oui, parce qu'il y a aussi des développeurs qui sont sentimentalement attachés à leur code. Alors, même quand ce code devient inutile, ils n'ont pas le coeur de le supprimer purement et simplement. Ils préfèrent juste le commenter, comme pour en conserver la trace (Pour info, ce trouble porte un nom : la syllogomanie).

• Réécrire le code en langage naturel : Parce que, c'est bien connu, même pour un développeur aguerri, lire du code, c'est dur. Alors, on va être gentil, et lui traduire le truc complet.

  // charge le fichier xml
  $xml = @simplexml_load_file( urlencode( $this->requestUrl ));
  // si le fichier n'a pas été bien chargé
  if( ! $xml ) {
      // récupère la dernière erreur
      $error = error_get_last();
      // enregistre un message de log
      sfContext::getInstance()->getLogger()->err( $error['message'] );
      // déclenche une exception
      throw new FeedburnerApiException( "Erreur de connexion à l'API FeedBurner" );
  }
  

  Ce genre de commentaire est tout à fait inutile : il alourdit le code source, impose au développeur de lire plus de choses, et n'importe absolument aucune information utile.

• Indiquer qui a introduit telle modification, ou corrigé tel bug :

  if ($i==0) $size = "font-size: 9pt;"; // thibault : fixes #453834
  else $size = "";
  

  Et les gestionnaires de source, c'est pour les chiens ? :)

• Trouver un excuse pour écrire un code compliqué : Ouais, d'accord, mon code est incompréhensible, mais c'est pas grave, je l'ai bien commenté.

En revanche, un commentaire sert à :

• Clarifier l'intention du développeur : Les commentaires sont utiles pour expliquer à un haut niveau d'abstraction pourquoi une portion de code a été écrite.
• Répondre à toute question légitime *dont la réponse ne se trouve pas dans le code* : Mon code est complexe ? J'ai utilisé un algorithme particulier ? Oui, mais il y a une bonne raison, alors, ne refactorisez pas, de toutes façons j'ai déjà testé toutes les solutions plus simples.
• Expliquer quelque chose de vraiment complexe : à condition que cette chose soit légitimement complexe, mais le cas est rare. Dans le cas contraire, mieux vaut simplifier le code d'abord.
• Générer la documentation d'un code réutilisable : dans le cas ou un code est écrit spécifiquement pour être réutilisé (API, bibliothèque de fonctions, framework, etc.), il est fort pratique d'utiliser des commentaires style javadoc pour générer automatiquement la documentation des interfaces publiques.
• Faciliter la lecture du code : Quelques commentaires bien placés peuvent aider à scanner le code et permettre de trouver plus facilement et rapidement la portion recherchée.

Alors, les commentaires, "c'est mieux quand yen a pas" ? En fait, point n'est besoin d'être aussi extremiste. En revanche, j'estime qu'il est bon d'écrire son code en partant du principe qu'il devra être compréhensible sans commentaire. C'est un état d'esprit qui ne peut qu'être bénéfique à la qualité et la lisibilité du code.

Seuls devraient être conservés les commentaires qui ne peuvent pas être supprimés, raccourcis ou refactorisés sans impacter sur la bonne lisibilité du code.

Et vous, qu'en pensez vous ? Les commentaires, glop ou pas glop ?