Commenter son code, c’est douter de son talent ?

---

Quand j’ai commencé à coder sérieusement en voulant en faire mon métier (et c’était y’a pas si longtemps) le monde du développement était bien différent, mais une chose, essentielle et commune à tous les langages était déjà présente, et ce depuis bien longtemps. Les commentaires.

---

Évidemment commenter son code c’est essentiel, du moins c’est ce qu’on nous rabâche très rapidement quand on commence à créé de réelles applications. Si chaque développeur gagnait un euro à chaque fois qu’on lui parle de commentaires, il n’y en aurait sûrement plus beaucoup en activité… (de développeurs j’entends)

Et bien sûr, au bout de quelques temps on comprend facilement leur intérêt et lors de nos premières code legacy, on les vénères. Mais il me semble important de revenir dessus et d’expliquer à quoi ils servent réellement, comment on doit les utiliser mais aussi pourquoi ils peuvent poser problème.

Pourquoi faire ?

C’est bateau mais oui les commentaires ont une utilité et il est important pour la suite de revenir dessus et d’essayer de ne rien oublier, et avec un peu de chance tu apprendras peut-être quelque chose.

Tout d’abord, le caractère informatif. Pour être totalement honnête c’est clairement sa seule utilité, donner des informations. Mais c’est la que le champs des possibles s’élargit. Pour qui ou quoi es-ce informatifs ? Et surtout quelles sont ces informations ?

On va commencer simple, les informations pour les développeurs, que ce soit toi dans un an ou n’importe quel autres dev qui doit intervenir sur ton code quelques temps plus tard.

On peut y retrouver de nombreuses informations différentes:

• Auteur du fichier

• Âge du fichier

• Le copyright

• L’utilité d’une classe

• La version d’une classe

• Le fonctionnement d’une méthode

• Des précisions sur des choix de développement

• Etc …

Bien sûr c’est non exhaustif et il est en vérité totalement possible d’écrire à peu près ce que tu veux tant que ça a une importance.

Mais c’est pas tout, ces mêmes informations peuvent servir à quelqu’un d’autre, enfin non ça reste utile à un développeur mais par un autre biais.. La documentation et la couverture de code.

Grâce à ces mêmes commentaires il est possible, comme je l’ai dit, de stipuler des informations sur des classes ou des méthodes qui peuvent être réutilisées par des scripts pour générer automatiquement des documentations complètes de ton application (PhpDoc, JsDoc, JavaDoc etc).

En plus de donner une information directe au développeur qui lit ton code, ta documentation offre une vision générale de l’application. Il est par exemple possible de préciser quels paramètres prend ta méthode en entrée et ce qu’on attend en sortie.

Ensuite viens les tests, on en entend parler autant voir plus que les commentaires et pour cause c’est super important (on y reviendra sûrement un jour) Et de la est née un besoin, la couverture de code. Cela permet de savoir à quel point ton application est testé, et pour cela il existe des scripts. Et encore une fois ces scripts on besoin de…..? COMMENTAIRES.

Bravo au deux au premier rang qui lisent encore.

Pour résumer, tes commentaires peuvent te servir à toi, aux développeurs qui viendront après, à créé une documentation complète et aussi à vérifier à quel point ton code est testé ou non (et donc prouver la viabilité à long terme de ton application).

Je pense qu’a ce niveau, et si ce n’était pas encore le cas. Tu es convaincu de l’utilité de commenter son code.

Mais du coup, es-ce qu’il y a une bonne façon de commenter ?

Comment faire ?

Pour répondre à ta super question. Oui, il y à de bonnes pratiques. Il existe plusieurs “types” de commentaires se différencient par leur place dans le fichier et par les informations qu’ils contiennent.

Faisons une petite liste avec des exemples :

• Le commentaire de fichier :

Il sert à stipuler les informations générales du fichier, son auteur ou son nom par exemple.

/*
 * UserController.php
 *
 * @author Axel.
 */

namespace App\Http\Controllers\Api\User;

use App\Http\Controllers;

class UserController extends ApiController {

....

}

• Le commentaire de classe :

Les informations propres à une classe, son utilité et pourquoi pas d’autres informations comme sa version d’implémentation, le développeur en charge de son développement etc …

/*
 * Logique controller des utlisateur
 * 
 * @class UserController
 * @since 3.1
 */
class UserController extends ApiController {

....

}

• Le commentaire de méthode :

Tout ce qui concerne une méthode, son fonctionnement, son utilité, ses paramètres etc …

 /**
  * Afficher la liste des utilisateur.
  * @param  \Illuminate\Http\Request  $request
  * @param  App\Models\User $user
  * @return \Illuminate\Http\Response
  */

  public function index(Request $request, User $user) {
      ...
  }

• Le commentaire de précision :

Ce sont les petits commentaires, directement écrit à l’intérieur du code, servant à justifier un choix ou à apporter des précisions sur un bout de code en particulier.

public function index(Request $request, User $user) {  
  // On autorise cette méthode qu'au token administrateur
  $this->authorize('adminManage', $user);  
  // On récupère la collection d'utilisateurs avec les paramètres
  return new UserCollection(User::with($this->withs)->get());
}

Bien sur, ce ne sont que des exemples, rien est vraiment gravé dans le marbre et les syntaxes et l’utilisation de ces différents commentaires peuvent varier selon le langage ou l’équipe dans laquelle tu bosse.

Que des avantages ?

Jusqu’ici on pourrait se dire que les commentaires, en plus d’être utiles et presque indispensables n’ont que des avantages, mais il n’en ai rien.

Il existe bien des inconvénients. De nombreux même, et c’est bien normal, plus un outil semble indispensable plus il est utilisé, parfois bien, et parfois mal.

Quand on y réfléchit un peu plus longuement, on se rend vite compte que de nombreux commentaires sont souvent facultatifs, ceux de “précisions” par exemple : Ils sont, la plupart du temps, un aveux de faiblesse.

“Mon code n’est pas très clair, je dois le commenter”.

Être conscient des problèmes de son code est une première étape, reste ensuite à apprendre comment nettoyer son code, le rendre plus lisible et parfois sacrifier la facilité pour la maintenabilité.

Regarde les commentaires de précision que je t’ai donné en exemple tout à l’heure :

public function index(Request $request, User $user) {  
  // On autorise cette méthode qu'au token administrateur
  $this->authorize('adminManage', $user);  
  // On récupère la collection d'utilisateurs avec les paramètres
  return new UserCollection(User::with($this->withs)->get());
}

Sont-ils réellement utiles ? Qu’elles informations apportent-ils que le code ne contient pas déjà ?

De plus, avec les documentations auto-générées et la couverture de code, on se retrouve très souvent avec des commentaires qui n’ont pas d’autre utilité que celle là, qui prennent parfois plus de place que le code lui même et qui rendent le code illisible.

Conclusion

Il faut donc apprendre à différencier un bon, d’un mauvais commentaire, savoir jauger la pertinence de certains et le superflus d’autres. Et surtout il faut être conscient de ces problématiques.

Bref, si le code parfait existait, il n’aurait pas besoin d’être commenté, et le commentaire parfait, lui, est celui qui n’a pas besoin d’être écrit.

---

Mais c’est pas non plus une raison pour pas commenter ton code compris ?