On peut dire que les commentaires de code sont plus importants que le code lui-même. Voici quelques moyens de garantir que les commentaires que vous écrivez dans votre code sont conviviaux :

Ne répétez pas ce que les lecteurs savent déjà

Les commentaires qui ne font qu'indiquer ce que fait le code ne nous sont pas utiles.

// If the color is red, turn it green 
if (color.is_red()) { 
    color.turn_green(); 
} 

Commentez pour expliquer le raisonnement et l'historique

Si la logique métier du code peut devoir être mise à jour ou modifiée plus tard, vous devriez laisser un commentaire.

/* The API currently returns an array of items 
even though that will change in an upcoming ticket. 
Therefore, be sure to change the loop style here so that 
we properly iterate over an object */ 
 
var api_result = {items: ["one", "two"]}, 
items = api_result.items, 
num_items = items.length; 
 
for(var x = 0; x < num_items; x++) { 
    ... 
}

Ne rendez pas les commentaires sur la même ligne trop longs

Rien n'énerve plus les développeurs que de devoir faire glisser la barre de défilement horizontale pour lire les commentaires. En fait, la plupart des développeurs choisiront d'ignorer ces commentaires, car ils sont vraiment peu pratiques à lire.

function Person(name) { 
    this.name = name; 
    this.first_name = name.split(" ")[0]; // This is just a shot in the dark here. If we can extract the first name, let's do it 
} 

Placez les commentaires longs au-dessus de la logique et les commentaires courts après

Les commentaires peuvent être placés à côté du code s'ils ne dépassent pas 120 caractères. Sinon, vous devriez placer le commentaire directement au-dessus de l'instruction.

if (person.age < 21) { 
    person.can_drink = false; // 21 drinking age 
 
    /* Fees are given to those under 25, but only in 
    some states. */ 
    person.has_car_rental_fee = function(state) { 
        if (state === "MI") { 
            return true; 
        } 
    }; 
}

N'ajoutez pas de commentaires inutiles juste pour commenter

Les commentaires trop verbeux peuvent prêter à confusion. Peut-être qu'à l'école, votre professeur vous a appris à ajouter des commentaires à toutes les instructions pour aider les développeurs à mieux comprendre. Mais c'est faux. Si quelqu'un dit cela, vous devriez immédiatement lui donner deux grandes claques. Le code doit rester propre et concis, cela ne fait aucun doute. Si votre code nécessite une explication ligne par ligne, alors ce dont vous avez le plus besoin, c'est de refactorisation.

if (person.age >= 21) { 
    person.can_drink = true; // A person can drink at 21 
    person.can_smoke = true; // A person can smoke at 18 
    person.can_wed = true; // A person can get married at 18 
    person.can_see_all_movies = true; // A person can see all movies at 17 
    //I hate babies and children and all things pure because I comment too much 
}

Veillez à ce que les commentaires soient correctement orthographiés

Ne cherchez pas d'excuses pour les fautes d'orthographe dans les commentaires de code. L'IDE peut vérifier l'orthographe pour vous. S'il n'a pas cette fonctionnalité, alors téléchargez un plugin et faites-le vous-même !

Pratiquez beaucoup

C'est en forgeant qu'on devient forgeron. Essayez d'écrire des commentaires utiles, et vous pouvez demander à d'autres développeurs si vos commentaires sont utiles. Avec le temps, vous comprendrez progressivement ce qui constitue des commentaires conviviaux.

Relisez les commentaires des autres

Lors de la revue de code, nous avons souvent tendance à ignorer les commentaires. N'ayez pas peur de demander plus de commentaires ; vous devriez poser des questions. Si tout le monde développe la bonne habitude d'écrire de bons commentaires, le monde sera meilleur.

Résumé

Les commentaires sont une partie très importante du processus de développement, mais nous ne devrions pas commenter pour commenter. Les commentaires doivent être utiles, concis et compléter le code. Les commentaires ne doivent pas servir à expliquer le code ligne par ligne ; ils doivent plutôt servir à expliquer la logique métier, le raisonnement et les implications pour l'avenir.