Que faire des commentaires ?

Cette article est une traduction de l’article Comments In Your Code. Il a été écrit par Daan sur le site medium.

En tant que développeur, vous savez que rien ne peut être aussi utile qu’un commentaire bien placé. Mais d’autre part, rien ne peut être aussi dommageable qu’un vieux commentaire qui contient des mensonges ou des informations erronées.
Alors, pourquoi pas les minimiser autant que possible dans votre code ?

Les commentaires sont, au mieux, un mal nécessaire.

Nous n’en aurions probablement pas besoin si nous avions des langages de programmation assez expressifs. La bonne façon d’utiliser un commentaire est de compenser notre incapacité à nous exprimer en code.

Les commentaires sont un échec de notre expression de pensée

Veuillez noter le mot échec dans la phrase précédente. Parce que c’est ce que sont les commentaires. Un échec de notre expression de pensée. La seule raison pour laquelle nous en avons dans notre code est que nous ne savons pas comment nous exprimer sans eux.
Alors posez-vous la question lorsque vous êtes sur le point d’insérer un commentaire dans votre code : n’y a-t-il pas moyen de m’exprimer clairement directement dans le code ?

La raison pour laquelle il faut minimiser l’utilisation de commentaires, est qu’ils contiennent des mensonges. Pas toujours, mais assez souvent.
La plupart du temps, cela ne se produit même pas intentionnellement.

Le code change, et il peut changer beaucoup. Alors les commentaires deviennent vieillissant, ils deviennent de moins en moins coh. La raison en est que les développeurs ne maintiendront pas de manière réaliste les commentaires.

Au fur et à mesure que le code est modifié ou refactorisé, des fragments de code seront probablement déplacés vers un emplacement différent. Malheureusement, les commentaires ne suivent pas toujours le code ou ne peuvent tout simplement pas le suivre.

Cela se traduit par des commentaires séparés du code original décrit, ce qui les rend de moins en moins précis.

Les commentaires inexacts sont bien pires que pas de commentaires du tout.

Vous pouvez indiquer que les développeurs doivent être suffisamment disciplinés pour conserver les commentaires et les maintenir exacts. Je suis entièrement d’accord. Mais je préférerais consacrer tous ces efforts à la rédaction d’un code aussi clair et expressif qu’il n’a pas besoin de commentaires.

La vérité ne peut être trouvée que dans une chose : le code. C’est la seule source d’informations véritablement précises. L’utilisation de commentaires, bien que parfois nécessaire, devrait être minimisée.

Commenter ne compensent pas le mauvais code

Parfois, la motivation pour écrire des commentaires est un mauvais code. Parfois, nous écrivons du code et nous savons que c’est un désastre.
Rappelez-vous que les commentaires ne compensent pas le mauvais code. Il vaut mieux nettoyer ce gâchis que de passer du temps à rédiger des commentaires.

Expliquez-vous dans le code

Cela ne prend que quelques secondes pour expliquer la plupart de vos intentions dans le code.
Dans de nombreux cas, il s’agit simplement de créer une méthode qui dit la même chose que le commentaire que vous écririez.
Préféreriez-vous voir l’exemple ci-dessous ?

// Check to see if game is finished and player can not spawn again
if ($game->status == GameStatus::FINISHED && $player->lives == 0)

Ou celui-ci ?

if ($game->isFinished())

N’utilisez pas de commentaire lorsque vous pouvez utiliser une méthode ou une variable.

Mauvais commentaires

Code commenté

Il existe une pratique simple en matière de commentaire de code : ne commentez pas.

D’autres développeurs penseront que le code existe pour une raison quelconque et n’auront pas le courage de le supprimer. Ils penseront qu’il est trop important de supprimer.

Supprimez simplement le code. Nous avons le contrôle de version, le code n’est pas perdu pour toujours.

2. Commentaires bruyant

Certains commentaires que vous voyez ne sont que du bruit. Ils réaffirment l’évidence et ne servent à rien.

public function __construct() {
    // Call the parent constructor
    parent::__construct();
}

Autre exemple :

/** The users name */ 
private $name;

/** The users age. */ 
private $age;

N’est-ce pas ?

3. Commentaires redondants

Un commentaire redondant n’est pas plus informatif que le code. Il ne justifie pas le code et ne fournit pas d’intention. Il ne fait qu’encombrer le code.

// Method that return true if when stream is open
// Throws an exception if stream is closed
public function waitForStreamClose() {
    if (!$this->closed) {
        return true;
    }    throw new Exception('Stream still open');
}

4. Commentaires journaliers

Parfois, les développeurs ajoutent un commentaire dans la partie supérieure de leur fichier chaque fois qu’ils le modifient.
Ne jamais faire ça. Les systèmes de contrôle de version, comme Git, existent pour cela.

Bon commentaires

Parfois, les commentaires sont utiles ou nécessaires.
Voici c-dessous, un exemple de bon commentaire, du fait qu’il contient des informations juridiques.

// Copyright (C) 2019 par Someone, Inc. Tous droits réservés.
// Publié sous les termes de la licence publique générale GNU

Ne commentez pas les contrats, faites plutôt référence à un document externe ou à une licence standard.

1. Commentaire informatif

Il peut parfois être utile de fournir des informations de base avec un commentaire.
Par exemple, dans des langages de programmation faiblement typés tels que PHP, vous pouvez fournir des informations de base sur un type de variable dans un commentaire.
Lorsque vous travaillez avec des dates, il peut être utile dans certains cas de taper un commentaire sur le format de date renvoyé par une méthode donnée.

2. Attention, danger

Lorsque vous travaillez avec plusieurs développeurs sur un projet, vous pouvez utiliser un commentaire pour avertir les autres développeurs de certaines conséquences.

// Takes a really long time to finish, only run at night.
private function synchroniseProducts()

3. To-do

Les commentaires to-do sont pour les tâches qu’un développeur doit faire, mais pour une raison quelconque ne peuvent pas être faites pour le moment.

Cela pourrait être un rappel de supprimer une fonctionnalité ou une fonction obsolète. Les commentaires à faire peuvent également être utilisés pour demander à une autre personne de penser à un meilleur nom ou d’effectuer un changement dépendant d’un événement planifié.

Conclusion

C’était mon article sur l’utilisation de commentaires dans votre code. Même s’il existe certaines formes de bons commentaires, je pense que vous devriez essayer d’en minimiser l’utilisation en général.

Merci de m’avoir lu!

Cet article est inspiré du livre Clean Code de Robert C. Martin, que je vous recommande vivement de lire.