Nommer les variables : quand la description est de trop

Quand on nomme des variables dans un programme, le conseil le plus courant est d’utiliser des noms descriptifs.

L’idée est qu’ils rendent le code plus simple à comprendre, en jouant un peu le rôle de commentaires intégrés.

Mais est-ce vraiment toujours la meilleure solution ? Voyons dans quels cas des noms plus courts et moins descriptifs peuvent au contraire améliorer la lisibilité.

​

Pourquoi utiliser des noms de variables descriptifs

Commençons par deux extraits de code identiques, sauf pour le nom des variables :

Extrait 1 : noms courts

1def count_above_threshold(x: int, y: list[int]) -> int:
2    """
3    Compter les éléments de la liste supérieurs au seuil.
4    """
5    s: int = 0
6    for a in y:
7        if a > x:
8            s += 1
9    return s

Extrait 2 : noms longs et descriptifs

1def count_above_threshold(threshold: int, numbers: list[int]) -> int:
2    """
3    Compter les éléments de la liste supérieurs au seuil.
4    """
5    count: int = 0
6    for number in numbers:
7        if number > threshold:
8            count += 1
9    return count

À première vue, le second extrait paraît plus clair, car threshold, numbers et count indiquent directement leur rôle.

À l’inverse, le premier extrait utilise des noms comme x, y et s, qui obligent le lecteur à deviner ce qu’ils représentent.

Mais cela veut-il dire qu’il faut toujours choisir des noms longs ? Pas forcément.

​

Quand les noms descriptifs deviennent contre-productifs

Même si les noms descriptifs aident dans la majorité des cas, il existe des situations où trop de verbosité diminue la clarté.

Prenons une fonction qui échange les éléments d’une matrice autour de la diagonale principale :

1def diagonal_swap(x: list[list[float]]):
2    """
3    Échanger les éléments autour de la diagonale principale de la matrice, en place.
4    """
5    n: int = len(x)
6    for i in range(n):
7        for j in range(i + 1, n):
8            x[i][j], x[j][i] = x[j][i], x[i][j]

Maintenant, la même fonction avec des noms plus longs :

1def diagonal_swap(matrix: list[list[float]]):
2    """
3    Échanger les éléments autour de la diagonale principale de la matrice, en place.
4    """
5    size: int = len(matrix)
6    for row_index in range(size):
7        for col_index in range(row_index + 1, size):
8            matrix[row_index][col_index], matrix[col_index][row_index] = \
9                matrix[col_index][row_index], matrix[row_index][col_index]

Quelle version est la plus lisible ? De façon surprenante, la première, même avec des noms courts.

Pourquoi ? Parce qu’ici, la précision des noms row_index et col_index n’apporte pas assez pour compenser la longueur du code.

Ce cas est fréquent dans les opérations mathématiques, notamment en calcul matriciel ou en calcul numérique.

Dans ces contextes, les opérations sont génériques et n’ont pas toujours besoin de noms descriptifs.

Par exemple, utiliser x et y dans une lambda Python est tout à fait acceptable :

1def product_list(list1: list[int], list2: list[int]):
2    return list(map(lambda x, y: x * y, list1, list2))

Remplacer x et y par value1 et value2 n’apporte rien :

1def product_list(list1: list[int], list2: list[int]):
2    return list(map(lambda value1, value2: value1 * value2, list1, list2))

Alors, comment choisir quels noms courts utiliser ? Est-ce vraiment important ?

​

Pourquoi certains noms courts fonctionnent bien

Si la version courte de diagonal_swap fonctionne si bien, ce n’est pas seulement grâce à sa concision.

C’est aussi parce que les noms courts sont choisis de manière cohérente.

Voyons ce qu’il se passe si on les renomme autrement :

1def diagonal_swap(x: list[list[float]]):
2    """
3    Échanger les éléments autour de la diagonale principale de la matrice, en place.
4    """
5    i: int = len(x)
6    for n in range(i):
7        for f in range(f + 1, i):
8            x[n][f], x[f][n] = x[f][n], x[n][f]

Cette version est moins naturelle. Pourquoi ?

Parce que i, n et f n’ont pas le sens habituel dans ce type d’algorithme.

Des lettres comme i, j et k sont couramment utilisées pour des indices.

De même, en Python, dans la gestion des exceptions, e est un nom court idiomatique pour représenter l’exception :

1try:
2    # du code susceptible de lever une exception
3except Exception as e:
4    print(e)

Renommer e en exception_object ajouterait seulement du bruit inutile.

Bref, les idiomes comptent dans le choix des noms courts. Les respecter rend ces noms plus lisibles.

Reprenons maintenant le second extrait de count_above_threshold, légèrement modifié :

1def count_above_threshold(threshold: int, numbers: list[int]) -> int:
2    """
3    Compter les éléments de la liste supérieurs au seuil.
4    """
5    count: int = 0
6    for a in numbers:
7        if a > threshold:
8            count += 1
9    return count

Ici, a est court, mais les paramètres threshold, numbers et count sont descriptifs, et le code reste très lisible.

Le rôle de a est immédiatement compris grâce à numbers. Pas besoin d’un nom long.

​

Quand les noms courts nuisent à la lisibilité

Parfois, réduire la verbosité en raccourcissant les noms peut rendre le code moins clair.

Exemple :

1...
2    # Mettre à jour la distance totale et le carburant consommé
3    total_distance += distance
4    total_fuel_used += fuel_used
5    n += 1
6
7# Calculer l'efficacité énergétique pour chaque véhicule
8for vehicle_id, metrics in trip_metrics.items():
9...

Que représente n ? Le contexte ne le dit pas clairement. Renommer résout le problème :

1...
2    # Mettre à jour la distance totale et le carburant consommé
3    total_distance += distance
4    total_fuel_used += fuel_used
5    trip_counts += 1
6
7# Calculer l'efficacité énergétique pour chaque véhicule
8for vehicle_id, metrics in trip_metrics.items():
9...

Le souci, ici, est que la signification de n n’est pas implicite dans son nom. Le lecteur doit remonter dans le code, ce qui casse la fluidité.

Pour ce type de situation, certains développeurs recommandent la règle de la portée courte :

Quand la variable est utilisée dans une portion réduite de code et que son usage est évident, un nom court est acceptable.

Gervais Yao Amoah

Cette règle dit que les noms courts ne doivent être utilisés que quand la portée est limitée et que le rôle est clair sans devoir chercher ailleurs.

Sinon, même si le nom long est plus verbeux, il présente plus d’avantages.

Pour réduire la verbosité, on peut aussi refactorer (par exemple, introduire des variables intermédiaires).

Et parfois, un autre critère peut dépasser la règle de la portée courte : la cohérence.

​

L’importance de la cohérence

Un point essentiel dans le nommage des variables est la cohérence.

Si ton équipe est habituée à utiliser i et j pour les indices, utiliser row_index et col_index à la place peut créer de la confusion — et inversement.

Dans l’écosystème Python, des bibliothèques comme NumPy et Pandas utilisent systématiquement des abréviations comme np ou df.

Ces conventions sont largement comprises et acceptées, ce qui garantit une lecture fluide.

À noter aussi que les conventions varient selon les langages : – en Haskell, des noms courts comme x et xs sont naturels, – en Java, les noms sont en général plus descriptifs, sauf contexte évident.

​

Conclusion

Les noms longs et descriptifs ne sont pas toujours la meilleure solution. Parfois, des noms courts rendent le code plus propre.

Quelques principes à garder en tête :

• Priorise la cohérence.
• Utilise des noms courts dans les opérations mathématiques génériques.
• Utilise des noms descriptifs quand ils n’alourdissent pas trop le code.
• Garde les noms courts (i, j, k, e) pour les boucles, indices et conventions reconnues.
• Choisis des noms courts idiomatiques lorsque c’est approprié.
• Évite les noms courts quand ils manquent de contexte et obligent le lecteur à remonter dans le code.

Cela s’applique surtout aux variables. Les classes, fonctions et enums doivent toujours avoir des noms clairs et descriptifs.

Cet article s’inspire du billet de blog de Tom Kwong sur le nommage. Il montre pourquoi des noms trop longs peuvent nuire à la lisibilité et quand les noms courts sont plus adaptés.

Tu connais d’autres cas où des noms courts améliorent la lisibilité ? Partage-les dans les commentaires !