Comprendre le code propre : commentaires ⚡️

Les commentaires de code sont considérés comme nécessaires dans le développement de logiciels, mais le livre Clean Code suggère que le code doit être explicite sans nécessiter de commentaires.

Nous découvrirons quand utiliser les commentaires, quand les éviter et comment rédiger des commentaires précieux dans le code JavaScript.

?Quand éviter les commentaires

1. Code évident :

Les commentaires ne doivent pas être utilisés pour expliquer ce que fait le code si cela ressort déjà clairement du code lui-même.

Par exemple :

// Increment the counter by 1
counter++;

// Check if the user is an admin
if (user.isAdmin()) {
    // ...
}

Dans ces cas, les commentaires sont redondants car le code est explicite. Au lieu d'ajouter des commentaires inutiles, concentrez-vous sur la création de votre code plus lisible.

2. Commentaires trompeurs :

Un commentaire qui ne correspond pas au code peut prêter à confusion et à des erreurs. Si vous mettez à jour le code mais oubliez de mettre à jour le commentaire, cela devient trompeur :

// Initialize user object
let user = new AdminUser(); // Actually, it's creating an AdminUser, not a regular user

Ici, le commentaire est trompeur et pourrait dérouter quelqu'un qui lirait le code plus tard. Il est préférable soit de supprimer le commentaire, soit de s'assurer qu'il reflète fidèlement le code.

3. Code commenté :

Laisser l'ancien code commenté est une mauvaise pratique courante. Cela encombre la base de code et peut prêter à confusion :

// Old code
// let data = fetchDataFromAPI();

// New code
let data = fetchDataFromDatabase();

Au lieu de laisser l'ancien code commenté, utilisez des systèmes de contrôle de version comme Git pour suivre les modifications du code. Cela permet de garder votre base de code propre et ciblée.

? Quand utiliser les commentaires

1. Intention de clarification :

Si un morceau de code a une logique complexe ou implique une solution de contournement, un commentaire peut clarifier pourquoi le code existe :

// Using a workaround for browser-specific bug in IE11
if (isIE11()) {
    fixIEBug();
}

Le commentaire explique pourquoi le code est nécessaire, fournissant un contexte précieux aux futurs développeurs.

2. Informations légales :

Parfois, les commentaires sont nécessaires pour des raisons juridiques, telles que l'inclusion d'informations sur les droits d'auteur ou de détails sur la licence :

/*
 * Copyright (c) 2024 MyCompany. All rights reserved.
 * Licensed under the MIT License.
 */

Ces commentaires sont essentiels et doivent être inclus comme l'exige la licence de votre projet.

3. Explication d'une décision :

Lorsqu'une décision spécifique du code nécessite une justification, un commentaire peut être utile :

// Using a binary search because the list is sorted
let index = binarySearch(sortedArray, target);

Ce commentaire explique pourquoi une recherche binaire a été choisie, donnant un aperçu du raisonnement derrière la mise en œuvre.

4. API publiques :

Lors de l'écriture d'API destinées au public, les commentaires peuvent aider à documenter comment les utiliser, en particulier en JavaScript où vous ne disposez peut-être pas d'outils de documentation intégrés :

/**
 * Calculates the area of a rectangle.
 * @param {number} width - The width of the rectangle.
 * @param {number} height - The height of the rectangle.
 * @returns {number} The area of the rectangle.
 */
function calculateArea(width, height) {
    return width * height;
}

Dans ce cas, le commentaire fournit une documentation claire sur la façon d'utiliser la fonction, ce qui est particulièrement utile pour les autres développeurs qui pourraient l'utiliser.

? Rédiger des commentaires utiles

• Soyez clair et concis : Les commentaires doivent être simples et précis. Évitez d'écrire des explications longues qui pourraient être facilement comprises à partir du code lui-même.

• Évitez le jargon : Utilisez un langage facile à comprendre, en évitant le jargon technique qui pourrait ne pas être familier à tous ceux qui lisent le code.

• Mettre à jour les commentaires : Mettez toujours à jour vos commentaires lorsque le code change. Une bonne règle de base est la suivante : si vous touchez le code, consultez les commentaires.

• Concentrez-vous sur le pourquoi, pas sur le quoi : Les bons commentaires expliquent pourquoi une décision particulière a été prise plutôt que de décrire ce que fait le code :
  

// We need to sort the array before performing the search
array.sort();

Ce commentaire explique pourquoi le tri est nécessaire avant la recherche, ajoutant ainsi un contexte précieux.

Conclusion ✅

Bien que les commentaires puissent être utiles, le Clean Code nous enseigne qu'ils doivent être utilisés avec parcimonie et à bon escient.

Le but est d'écrire du code si clair que les commentaires deviennent presque inutiles.

Lorsque des commentaires sont requis, assurez-vous qu'ils sont significatifs et précis, et qu'ils apportent de la valeur à toute personne lisant votre code.

En suivant ces directives, vous améliorerez non seulement la qualité de votre code, mais vous permettrez également aux autres (et à vous-même) de le comprendre et de le maintenir plus facilement.

Bon codage !

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!