Je ne suis personnellement jamais tombé sur du code qui abuse de commentaires. Il n’est pas simple, pour un junior/nouvel arrivant de savoir quand il est pertinent de commenter ou non. En cas de doute, j’aurais tendance à dire qu’il vaut mieux risquer d’écrire un commentaire inutile que d’en omettre un important.
Concernant les abréviations. Je suis d’accord qu’il faut les éviter par défaut, mais il peut être intéressant de faire une liste blanche de termes quand ils sont très souvent utilisés. Cette liste doit être discutée. Le but n’est pas d’en mettre partout, mais sur les noms de variable les plus utilisés, suivant le domaine.
Une technique pour qu’une personne s’améliore est de combiner la maintenance de ses propres outils, avec le débogage d’outils bien codé. Ça permet à la personne de se rendre compte par elle-même de l’intérêt d’avoir des choses propres.
Pour les commentaires, je suis tombé sur un code où CHAQUE ligne était précédée d’un commentaire. Avec ma ligne préférée :
// Incrémente i
i++;
Après lui avoir demandé pourquoi il le faisait, le développeur m’a dit “les profs m’ont dit de tout commenter”. C’est donc ce qu’il faisait.
Lorsque je code, j’applique le principe suivant :
Ce que le code est sensé faire : c’est le nom de la méthode/fonction
Ce que le code fait : ce sont les tests (mais normalement, le code est devrait faire ce qu’il est … sensé faire)
Comment le code le fait : c’est le code justement. Soit il est clair ou classique et il y a pas besoin de le commenter (au développeur qui lit de se former), soit il est “compliqué” et il y vaut mieux trouver moyen de faire autrement et sinon, voir suivant.
Pourquoi le code le fait comme ça : seule raison pourquoi je commente (pourquoi j’utilise telle constante, tel patron, telle répartition de responsabilité, …)
Merci !
C’est sûr qu’il n’est pas simple pour un junior de savoir quand le commentaire est pertinent. C’est pourquoi il faut toujours se demander, quand on écrit un commentaire, si le code ne pourrait pas être simplifié. Après je suis assez d’accord avec toi qu’il vaut mieux écrire un commentaire inutile que d’en omettre un important mais cela doit, selon moi, être vu lors revue de code pour justement nettoyer les commentaires inutiles.
Sympa ta liste ! Je ne suis pas forcément d’accord avec certaines abréviations (hrchy ou cnt par exemple) mais de définir une liste blanche de termes ce n’est pas bête même si dans l’idéal il faut les éviter.
Sinon pour s’améliorer, rien de tel que le pair programming et la revue de code avec la personne concernée.
Merci pour l’article. Il est très bien écrit.
Je ne suis personnellement jamais tombé sur du code qui abuse de commentaires. Il n’est pas simple, pour un junior/nouvel arrivant de savoir quand il est pertinent de commenter ou non. En cas de doute, j’aurais tendance à dire qu’il vaut mieux risquer d’écrire un commentaire inutile que d’en omettre un important.
Concernant les abréviations. Je suis d’accord qu’il faut les éviter par défaut, mais il peut être intéressant de faire une liste blanche de termes quand ils sont très souvent utilisés. Cette liste doit être discutée. Le but n’est pas d’en mettre partout, mais sur les noms de variable les plus utilisés, suivant le domaine.
J’ai une petite liste de termes qui reviennent.
Une technique pour qu’une personne s’améliore est de combiner la maintenance de ses propres outils, avec le débogage d’outils bien codé. Ça permet à la personne de se rendre compte par elle-même de l’intérêt d’avoir des choses propres.
Pour les commentaires, je suis tombé sur un code où CHAQUE ligne était précédée d’un commentaire. Avec ma ligne préférée :
Après lui avoir demandé pourquoi il le faisait, le développeur m’a dit “les profs m’ont dit de tout commenter”. C’est donc ce qu’il faisait.
Lorsque je code, j’applique le principe suivant :
Merci ! C’est sûr qu’il n’est pas simple pour un junior de savoir quand le commentaire est pertinent. C’est pourquoi il faut toujours se demander, quand on écrit un commentaire, si le code ne pourrait pas être simplifié. Après je suis assez d’accord avec toi qu’il vaut mieux écrire un commentaire inutile que d’en omettre un important mais cela doit, selon moi, être vu lors revue de code pour justement nettoyer les commentaires inutiles.
Sympa ta liste ! Je ne suis pas forcément d’accord avec certaines abréviations (hrchy ou cnt par exemple) mais de définir une liste blanche de termes ce n’est pas bête même si dans l’idéal il faut les éviter.
Sinon pour s’améliorer, rien de tel que le pair programming et la revue de code avec la personne concernée.