Comment Écrire de Meilleurs Noms pour Vos Variables, Fonctions et Classes – Avec des Exemples

La nomination est l’une des parties les plus importantes et les plus difficiles de l’écriture de code propre, maintenable et évolutif. Par exemple, un nom de variable bien pensé peut servir de code auto-documenté, ce qui permet de gagner du temps et des efforts dans la compréhension de la logique. Mais des noms mal choisis, d’autre part, peuvent entraîner confusion et bogues.

Cet article servira de guide complet sur la manière de trouver des noms significatifs pour les noms de classes, les variables et les fonctions, avec des exemples et les meilleures pratiques.

Pourquoi la nomination est-elle importante?

• Lisibilité: Les bons noms rendent votre code intuitif et réduisent la courbe d’apprentissage pour les autres.

• Maintenabilité: Il est plus facile de refactoriser ou de déboguer un code bien nommé.

• Collaboration: Des noms clairs améliorent la communication et la productivité de l’équipe.

• Évolutivité: Des noms significatifs aident à maintenir la gestion de grands projets.

Différents Styles de Conventions de Nomage

Les différents styles de conventions de nommage sont cruciaux pour améliorer la lisibilité du code et sa maintenabilité à travers divers langages de programmation.

Les styles comme camelCase, PascalCase, snake_case et kebab-case sont adaptés à des contextes et des pratiques spécifiques.

camelCase est largement utilisé pour les variables et les fonctions, tandis que PascalCase est préféré pour les classes. snake_case est un favori en Python pour sa clarté, et kebab-case domine le CSS pour la mise en forme des éléments HTML.

Chaque style garantit la cohérence, rendant le code intuitif pour les équipes et les futurs développeurs. Voici un tableau récapitulatif rapide de quelques conventions de nommage populaires avec leurs cas d’utilisation et exemples :

Comment choisir le bon style

1. Spécifique au langage : Suivez les conventions de votre langage de programmation ou de votre framework. Par exemple :

   • JavaScript : camelCase pour les variables et les fonctions, PascalCase pour les composants.

   • Python : snake_case pour les variables et les fonctions.

   • CSS/HTML : kebab-case pour les noms de classes et les identifiants.

2. Normes de l’équipe ou du projet : La cohérence est essentielle. Utilisez le style convenu pour votre équipe/projet.

3. Spécifique au but: Utilisez des styles de nommage qui représentent au mieux l’entité nommée (par exemple, les constantes en SCREAMING_SNAKE_CASE).

Directives générales de nommage

Avant de plonger dans des conventions de nommage spécifiques pour les noms de classe, les variables et les fonctions, explorons quelques principes universels:

1. Sois descriptif et concis: Les noms doivent transmettre le but ou le rôle de la variable/fonction/etc:

    // Mauvais
    let x = 10;
   
    // Bon
    let maxUtilisateursPermis = 10;
   

2. Évitez les abréviations cryptiques qui pourraient être difficiles à comprendre pour d’autres développeurs (ou même pour votre futur vous) :

    // Mauvais
    let usrNm = "John";
   
    // Bon
    let userName = "John";
   

3. Utilisez des conventions de nommage cohérentes : Choisissez un style de nommage (camelCase, PascalCase, kebab-case, snake_case) et tenez-vous-y tout au long de votre projet.

4. Évitez les mots-clés réservés ou les noms confus :

    // Mauvais
    let let = 5;
   
    // Bon
    let nomDeVariable = 5;
   

Très bien, maintenant que nous avons couvert les bases, plongeons plus en profondeur dans certaines conventions de nommage utiles.

Comment créer de bons noms de classe

Les noms de classe définissent le comportement visuel ou structurel des éléments de votre application. Écrire des noms de classe clairs garantit que votre HTML et votre CSS sont faciles à comprendre et à maintenir.

1. Utilisez des noms descriptifs

Les noms de classe doivent décrire le but de l’élément, pas son apparence.

<!-- Mauvais -->
<div class="red-button"></div>

<!-- Bon -->
<div class="primary-button"></div>

2. Suivez la méthodologie BEM (Block-Element-Modifier)

BEM est une convention populaire pour écrire du CSS évolutif et maintenable. Il sépare les composants en :

• Bloc : Représente le composant (par exemple, carte).

• Élément : Représente les éléments enfants du bloc (par exemple, carte__titre).

• Modificateur : Représente les variations du bloc ou de l’élément (par exemple, carte__titre--souligné).

Exemple :

<div class="card">
  <h1 class="card__title card__title--highlighted">Welcome</h1>
  <p class="card__description">This is a card component.</p>
</div>

3. Utiliser le kebab-case

Les noms de classes CSS sont traditionnellement écrits en kebab-case pour une meilleure lisibilité.

<!-- Mauvais -->
<div class="primaryButton"></div>

<!-- Bon -->
<div class="primary-button"></div>

Comment créer de bons noms de variables

Les variables contiennent des données et doivent avoir des noms significatifs qui décrivent ce qu’elles représentent.

1. Utiliser des noms communs pour les variables

Les variables sont généralement des noms communs car elles représentent des entités ou des données.

// Mauvais
let a = "John";

// Bon
let userName = "John";

2. Utiliser des préfixes pour ajouter du contexte

Ajouter des préfixes aide à clarifier le type ou l’objectif d’une variable :

• Booléen: est, possède, peut

• Nombres: max, min, total

• Tableaux: Utilisez des formes au pluriel (par exemple, utilisateurs, éléments).

Exemple:

let isUserLoggedIn = true;
const maxUploadLimit = 5; // Mo
const usersList = ["John", "Jane"];

3. Évitez les Noms Génériques

Évitez les noms comme données, valeur, ou élément sauf s’ils sont nécessaires.

// Mauvais
let data = 42;

// Bon
let userAge = 42;

Comment Créer de Bons Noms de Fonctions

Les fonctions exécutent des actions, donc leurs noms doivent refléter l’opération ou le processus qu’elles exécutent.

1. Utilisez des Verbes pour les Fonctions

Les fonctions sont orientées action, donc leurs noms doivent commencer par un verbe :

// Mauvais
function userData() {
  // ...
}

// Bon
function fetchUserData() {
  // ...
}

2. Soyez Spécifique Concernant la Fonctionnalité

Les noms de fonctions doivent indiquer ce qu’elles font.

// Mauvais
function handle() {
  // ...
}

// Bon
function handleFormSubmit() {
  // ...
}

3. Utilisez des préfixes pour l’intention

• Pour les gestionnaires d’événements : handle, on

• Pour les utilitaires : calculate, convert, format

• Pour les opérations de récupération : fetch, get, load

• Pour les setters et getters : set, get

Exemple :

function handleButtonClick() {
  console.log("Button clicked!");
}

function calculateDiscount(price, discountPercentage) {
  return price * (discountPercentage / 100);
}

Comment savoir si un nom est bon pour une variable, une fonction ou une classe

Pour comprendre si un nom est adapté pour une variable, une fonction ou une classe, il est important de l’évaluer en utilisant plusieurs principes clés. Voici un guide pour vous aider à décider si un nom est approprié et significatif dans votre contexte de programmation :

1. Représente-t-il le but ?

Les noms axés sur un objectif sont la caractéristique la plus importante d’un bon nommage. Un nom doit immédiatement indiquer ce que représente ou fait la variable, la fonction ou la classe sans avoir besoin de lire des commentaires ou de la documentation supplémentaires.

Comment évaluer :

Demandez-vous : « Lorsque je lis ce nom, puis-je immédiatement comprendre son objectif ? »

Exemple :

• userAge est mieux que a car userAge indique ce que représente la variable, tandis que a est trop ambigu.

2. Est-il suffisamment spécifique ?

Le nom doit être suffisamment spécifique pour refléter le rôle exact de l’entité dans votre code. Des noms trop génériques comme data ou temp peuvent être déroutants car ils ne fournissent pas suffisamment de contexte.

Comment évaluer :

Demandez : « Ce nom est-il spécifique à ce que cette variable, fonction ou classe représente dans mon application ? »

Exemple :

• calculateTaxAmount() est mieux que calculate() car il est clair ce que la fonction calcule.

3. Suit-il une convention de nommage cohérente ?

La cohérence dans les conventions de nommage est essentielle. Lorsque tous les membres de l’équipe suivent les mêmes conventions, le code est plus facile à comprendre et à naviguer.

Comment évaluer :

Demandez : « Ce nom est-il cohérent avec les conventions de nommage utilisées dans le reste du projet ? » Suivez les directives du projet telles que :

• camelCase pour les variables et fonctions (par exemple, userAge)

• PascalCase pour les classes (par exemple, UserProfile)

• UPPERCASE_SNAKE_CASE pour les constantes (par exemple, MAX_USERS)

Exemple :

• Si votre équipe suit le camelCase, userData est mieux que UserData.

4. Cela Évite-t-il l’Ambiguïté ?

Un bon nom élimine l’ambiguïté. Il ne devrait pas être sujet à plusieurs interprétations. S’il peut signifier différentes choses dans différents contextes, cela entraînera de la confusion.

Comment Évaluer :

Demandez : « Est-ce qu’une personne non familière avec le code pourrait interpréter incorrectement à quoi ce nom fait référence ? »

Exemple :

• Au lieu de nommer un booléen isValid, utilisez isUserLoggedIn ou isEmailVerified pour rendre plus clair ce qui est vérifié.

5. Est-il Facile à Lire et à Prononcer ?

Bien que ce ne soit pas strictement nécessaire, la facilité de lecture et de prononciation peut améliorer la lisibilité et la maintenabilité globales de votre code.

Comment évaluer :

Demandez : « Ce nom est-il facile à lire à voix haute, et puis-je le comprendre d’un coup d’œil ? »

Évitez les noms longs et utilisez des abréviations courantes uniquement lorsqu’elles sont largement acceptées.

Exemple :

• maxRetries est préférable à maximumNumberOfAttemptsToReconnect.

6. Évite-t-il la redondance ?

Évitez la redondance dans les noms. Ne répétez pas des informations qui sont déjà implicites ou décrites par le contexte.

Comment évaluer :

Demandez : « Suis-je en train de répéter des informations qui sont déjà claires dans le contexte environnant ? »

Exemple :

• Si vous avez une classe nommée User, nommer une méthode userGetData() est redondant. Utilisez plutôt getData().

7. Est-ce auto-documenté ?

Les meilleurs noms s’auto-documentent. De bons noms réduisent le besoin de commentaires ou d’explications supplémentaires.

Comment évaluer :

Demandez : « Ce nom décrit-il complètement la variable, la fonction ou la classe sans nécessiter un commentaire pour expliquer ce qu’il fait ? »

Exemple :

• La fonction calculateTotalPrice est explicite, donc pas besoin d’un commentaire supplémentaire comme « Cette fonction calcule le prix total après réduction. »

8. Est-ce Contextuel et Pertinent pour le Domaine?

Le nom doit correspondre au contexte de votre projet et de son domaine. Par exemple, les conventions de nommage pour une application web peuvent différer de celles pour une application mobile ou un modèle d’apprentissage automatique.

Comment Évaluer:

Demandez-vous : « Ce nom est-il aligné avec le domaine et le contexte de mon projet? »

Si vous travaillez dans un domaine spécifique (par exemple, la finance, la santé, les jeux), utilisez des termes spécifiques au domaine facilement reconnaissables.

Exemple:

• Dans une application de jeu, healthPoints est plus approprié que hp, car il reflète sa signification.

9. Est-ce Anticipatif?

Envisagez l’évolution de votre code. Les noms doivent être suffisamment flexibles pour accommoder les changements futurs sans nécessiter de refactoring.

Comment Évaluer:

Demandez-vous : « Ce nom restera-t-il pertinent si la fonctionnalité évolue ou si le projet grandit? »

Exemple:

• userInfo pourrait devenir obsolète si la structure de données change. Il est préférable d’utiliser userProfile si vous prévoyez l’ajout de champs supplémentaires.

10. Évite-t-il les Nombres Magiques et les Valeurs Codées en Durée?

Les nombres magiques (nombres dont la signification est floue) doivent être évités au profit de constantes nommées.

Comment évaluer :

Demandez : « Ce nom représente-t-il une constante significative, ou s’agit-il simplement d’un nombre brut ? »

Exemple :

• Au lieu d’utiliser 1000, utilisez une constante comme MAX_FILE_SIZE pour expliquer la signification derrière le nombre.

Exemples pratiques

Exemple CSS

L’exemple CSS suivant démontre comment appliquer les conventions de nommage BEM (Block-Element-Modifier) pour maintenir une hiérarchie de classes structurée et évolutive dans votre feuille de style :

<!-- HTML -->
<div class="navbar">
  <ul class="navbar__list">
    <li class="navbar__item navbar__item--active">Home</li>
    <li class="navbar__item">About</li>
    <li class="navbar__item">Contact</li>
  </ul>
</div>

/* CSS */
.navbar {
  background-color: #333;
  padding: 10px;
}

.navbar__list {
  list-style: none;
}

.navbar__item {
  display: inline-block;
  padding: 10px;
}

.navbar__item--active {
  color: orange;
}

Voici ce qui se passe dans ce code :

• Nommage BEM : navbar est le Block, représentant le composant principal de navigation.

• navbar__list est l’Element, un enfant du block, représentant la liste des éléments de navigation.

• navbar__item est un autre Element représentant des éléments de liste individuels.

• navbar__item--active est un Modificateur, utilisé pour mettre en évidence l’élément de menu actif.
  Cette approche facilite la compréhension des relations et des rôles au sein du HTML et du CSS, soutenant des styles modulaires et réutilisables.

Exemple JavaScript

Cet exemple JavaScript montre comment utiliser des conventions de nommage significatives et cohérentes pour les variables et les fonctions afin de rendre le code explicite :

// Variables
let isUserLoggedIn = false;
const maxAllowedItems = 10;

// Fonctions
function fetchUserDetails(userId) {
  // Récupérer les données utilisateur depuis l'API
}

function calculateTotalPrice(cartItems) {
  return cartItems.reduce((total, item) => total + item.price, 0);
}

Voici ce qui se passe dans le code :

• Variables :

  • isUserLoggedIn : Une variable booléenne nommée pour indiquer clairement son but. Le préfixe is aide à l’identifier comme une booléenne.

  • maxAllowedItems : Une constante avec un préfixe max en majuscule montre qu’il s’agit d’une limite, rendant son intention claire.

• Fonctions:

  • fetchUserDetails(userId): Le nom reflète le but de la fonction, qui est de récupérer les détails de l’utilisateur. Le paramètre userId est descriptif et évite les ambiguïtés.

  • calculateTotalPrice(cartItems): Le nom de la fonction indique explicitement l’action effectuée. Le paramètre cartItems est contextuellement pertinent pour le domaine du commerce électronique.

Pourquoi c’est bien: Ces conventions garantissent que le code est lisible et intuitif, réduisant la charge cognitive pour les autres développeurs travaillant sur le même projet.

Conclusion

Donner des noms significatifs est à la fois une convention importante et un art qui a un impact significatif sur la lisibilité et la maintenabilité de votre code.

Essayez de suivre ces principes de base :

• Utilisez des noms descriptifs et concis.

• Respectez des conventions cohérentes comme BEM pour les noms de classe et camelCase pour les variables et les fonctions.

• Utilisez des préfixes pour ajouter du contexte et de la clarté.

Ces conseils, ainsi que d’autres que nous avons discutés ici, rendront votre code agréable à travailler, que vous le revisitez des mois plus tard ou que vous collaborez avec une équipe. Commencez à appliquer ces conseils aujourd’hui et regardez la qualité de votre code s’élever.