Commentaires Python - Écrivez-les bien, rendez votre code clair

Un bon commentaire Python ne répète pas le code : il explique une intention, une contrainte ou un choix qui ne saute pas aux yeux. C’est souvent la différence entre un fichier qui se relit vite et un bloc de logique qui devient fragile dès la première modification. Ici, je passe en revue la syntaxe de base, les bons usages, la différence entre commentaires et docstrings, puis la méthode que j’utilise pour garder un code clair sans le surcharger.

Ce que fait vraiment un commentaire en Python

En Python, un commentaire est une instruction ignorée par l’interpréteur. Il commence avec #, peut apparaître en début de ligne ou après du code, et s’arrête à la fin de la ligne. Il ne peut pas vivre à l’intérieur d’une chaîne de caractères : si le caractère # est dans une chaîne, il fait simplement partie du texte.

Je rappelle souvent ce point parce qu’il change la façon de raisonner : un commentaire ne modifie jamais le comportement du programme. Son rôle est uniquement documentaire. Autrement dit, si votre logique est claire sans aide, il ne faut pas ajouter un commentaire par réflexe ; si elle ne l’est pas, il faut d’abord se demander si le code peut être rendu plus lisible avant d’ajouter une explication.

# Calcule le total après remise
total = prix * (1 - remise)

texte = "# Ce caractère est du texte, pas un commentaire"

Dans un fichier partagé avec une équipe, je conseille aussi de garder les commentaires dans une seule langue, idéalement celle du projet. Si vous écrivez en français avec des accents, conservez vos fichiers en UTF-8 pour éviter les surprises d’encodage. Une fois cette mécanique posée, la vraie question n’est plus de savoir où placer le #, mais quoi écrire derrière.

Écrire un commentaire utile sans alourdir le code

Le bon commentaire répond à une question que le code ne peut pas répondre seul. Dans la pratique, je me sers de trois critères simples : est-ce que cela explique une contrainte, un compromis ou une intention métier ? Est-ce que cela restera vrai après une petite refactorisation ? Est-ce que la phrase apporte une information que le nom de variable ou de fonction ne donne pas déjà ?

• Expliquez le pourquoi, pas le quoi. Si la ligne dit déjà ce qu’elle fait, le commentaire doit ajouter le contexte.
• Gardez une phrase complète. Une majuscule au début et un point à la fin rendent le texte plus propre et plus lisible.
• Préférez un bloc de commentaire au-dessus du code quand l’explication s’applique à plusieurs lignes.
• Réservez les commentaires en ligne aux cas vraiment courts, quand une seule précision suffit.
• Relisez après chaque changement. Un commentaire qui décrit une ancienne logique devient vite un piège.

# L'API partenaire refuse les montants au-dessus de 10 000 EUR.
if montant > 10_000:
    raise ValueError("Montant non conforme")

if montant > 10_000:
    raise ValueError("Montant non conforme")  # Vérifie que le montant est valide

Le second exemple est faible parce qu’il répète le code. Le premier est plus utile : il explique une règle externe, donc une information que la ligne Python ne peut pas exprimer seule. Quand le commentaire dépasse une phrase, je préfère souvent le déplacer vers une docstring ou vers un nom plus parlant.

Choisir entre commentaire, docstring et nom explicite

Dès qu’un texte commence à devenir un mini-paragraphe, je me demande s’il doit vraiment rester un commentaire. En Python, il existe trois leviers différents, et les confondre produit vite des fichiers lourds à maintenir : le commentaire local, la docstring et le nom explicite.

def normaliser_slug(titre: str) -> str:
    """Retourne une version compatible URL du titre fourni."""
    ...

Je réserve les docstrings aux interfaces qui comptent vraiment : modules, fonctions, classes, méthodes publiques. Une docstring n’est pas un commentaire au sens strict, c’est une chaîne de caractères placée en première instruction. Elle documente l’API, alors qu’un commentaire local explique un détail d’implémentation ou une décision ponctuelle. Ce tri évite une erreur fréquente : garder des commentaires qui auraient dû être une simplification du code.

Les erreurs que je vois le plus souvent

Les commentaires les plus faibles ont presque toujours le même défaut : ils ne disent rien de neuf. À force de relire des dépôts, j’ai fini par repérer quelques signaux d’alerte très nets.

• Commenter l’évidence. Dire qu’une ligne additionne, copie ou incrémente quelque chose n’apporte rien.
• Laisser un commentaire périmé. C’est pire qu’un manque de commentaire, parce que le lecteur lui fait confiance à tort.
• Accumuler les commentaires en ligne. Si chaque instruction en a besoin, le code est probablement trop dense.
• Utiliser le commentaire pour masquer un mauvais nom. Un nom de variable clair vaut souvent mieux qu’une phrase de secours.
• Transformer un commentaire en journal de bord. Les TODO et les notes provisoires doivent rester temporaires, sinon ils s’installent pour de bon.

Dans un backend ou une base de code orientée produit, je fais aussi attention aux commentaires qui stockent des hypothèses sensibles : dépendance à une API, règle de sécurité, comportement d’un tiers, contournement temporaire. Ce sont exactement les zones où un commentaire peut aider, mais aussi où il faut le maintenir avec rigueur. C’est précisément pour ça que j’aime travailler par passes successives plutôt que d’ajouter des blocs de texte au fil de l’eau.

Ma méthode pour commenter un module sans le surcharger

Quand je reprends un module Python, je procède presque toujours dans le même ordre. Ce n’est pas plus long, mais cela évite les commentaires décoratifs et les explications écrites trop tôt.

1. Je lis d’abord le code sans écrire de commentaire. Je cherche les endroits où la logique devient non évidente : règle métier, exception, dépendance externe, contrainte de sécurité, effet secondaire.
2. Je pose une docstring sur l’interface publique. Si la fonction, la classe ou le module est réutilisé ailleurs, l’objectif doit être lisible immédiatement.
3. Je n’ajoute un commentaire de bloc que là où une séquence de lignes porte une intention particulière. Une petite série d’instructions peut mériter une phrase, pas quatre.
4. Je limite les commentaires en ligne aux cas vraiment atypiques. Par exemple, un contournement, une donnée héritée d’un système externe ou un choix technique qui surprendrait un lecteur.
5. Je fais une relecture après refactorisation. Si le commentaire ne survit pas à cette relecture, il fallait probablement réécrire le code plutôt que l’expliquer.

# On garde ce format pour rester compatible avec l'API partenaire.
payload = {
    "price": prix,
    "currency": "EUR",
}

def calculer_tva(prix_ht: float) -> float:
    """Retourne le montant de TVA appliqué au prix hors taxe."""
    return prix_ht * 0.2

Cette méthode me donne un bon équilibre : assez de texte pour documenter ce qui ne se devine pas, pas assez pour transformer le fichier en prose. Si un commentaire commence à devenir une justification longue, je vois cela comme un indice de dette de lisibilité, pas comme un succès rédactionnel.

Le meilleur commentaire est parfois une meilleure structure

Le moyen le plus efficace de réduire le bruit, ce n’est pas de supprimer tous les commentaires : c’est de faire en sorte qu’ils deviennent rares. J’obtiens souvent un meilleur résultat en modifiant la structure du code qu’en ajoutant une explication supplémentaire.

• Renommez les variables opaques. Un tmp, res ou data mal contextualisé pousse presque toujours à écrire un commentaire de secours.
• Découpez les fonctions trop longues. Si une fonction fait trois choses, elle aura besoin de trois niveaux de lecture.
• Extrayez les constantes. Les valeurs magiques sont des aimants à commentaires.
• Utilisez les types et les tests. Ils ne remplacent pas les commentaires, mais ils clarifient le contrat et réduisent les ambiguïtés.
• Gardez les commentaires pour l’exception, pas pour la règle. La règle devrait vivre dans la structure du code.

En pratique, je pars toujours de ce principe : si une ligne reste claire sans commentaire, je la laisse nue ; si une intention n’est pas évidente, j’ajoute une phrase courte ; si l’explication devient longue, je remonte d’un niveau et je simplifie le code. C’est ce tri qui garde un projet Python lisible, surtout quand l’équipe grossit ou que le fichier revient sur le bureau six mois plus tard.