Commenter son code Python - Utile ou nuisible ?

Quand je relis du code Python, je cherche d’abord si les commentaires m’aident vraiment à comprendre une décision, une contrainte métier ou un point technique qui ne saute pas aux yeux. C’est là que la bonne pratique fait la différence: un commentaire utile clarifie, un mauvais commentaire surcharge, et un commentaire faux devient vite un problème. Ici, je vais montrer la syntaxe réelle, la différence entre commentaires et docstrings, puis les réflexes simples qui gardent un script lisible sans le noyer sous le texte.

Comment Python interprète un commentaire

En Python, tout commentaire commence par #, à condition que ce caractère ne fasse pas partie d’une chaîne de caractères. Le moteur ignore ensuite tout ce qui suit sur la ligne. En pratique, cela veut dire qu’un commentaire peut être isolé sur sa propre ligne ou placé à la fin d’une instruction, ce qu’on appelle souvent un commentaire en ligne.

Le point important, c’est que le commentaire ne change rien à l’exécution. Il ne produit pas d’effet, il n’entre pas dans la logique du programme et il ne remplace pas une instruction. Je rappelle aussi un détail que beaucoup oublient: un # dans une chaîne, comme "# note interne", n’est pas un commentaire. C’est juste du texte.

# Ceci est un commentaire
message = "#ceci n'est pas un commentaire"
print(message)  # Affiche la chaîne telle quelle

Autre subtilité utile: une ligne continuée avec un antislash ne doit pas porter de commentaire. Si votre code devient trop long, je recommande plutôt les parenthèses que les retours ligne bricolés. C’est plus propre, plus lisible et moins fragile lors des relectures.

Une fois cette mécanique claire, la vraie question devient celle de l’usage: comment commenter une ligne sans encombrer tout le fichier.

Commenter une ligne, un bloc ou une portion de code

Python ne propose pas de syntaxe spéciale pour un bloc commentaire au sens strict. La méthode standard consiste à répéter # au début de chaque ligne concernée. C’est simple, explicite, et ça évite les ambiguïtés que l’on voit parfois dans d’autres langages.

Pour commenter proprement un bloc, je préfère garder le texte court et homogène. Par exemple:

# On filtre d'abord les entrées invalides.
# Ce contrôle évite de propager des valeurs nulles plus loin.
records = [r for r in records if r is not None]

Le piège classique, c’est de commenter du code juste pour le commenter, sans ajouter d’information. Si la ligne est déjà claire, le commentaire devient du bruit. Dans un dépôt partagé, ce bruit coûte du temps à tout le monde lors des revues de code.

Cette distinction mène naturellement à un sujet souvent confondu avec les commentaires: les docstrings, qui ne jouent pas du tout le même rôle.

Quand préférer une docstring à un commentaire

Une docstring est une chaîne de caractères placée en première instruction d’un module, d’une classe, d’une fonction ou d’une méthode. Python la conserve dans l’attribut __doc__, ce qui permet à des outils comme help() de l’afficher. Ce n’est donc pas un commentaire au sens strict, même si, dans l’esprit, elle sert aussi à documenter.

Je fais la différence de cette manière: le commentaire explique une décision locale, la docstring décrit un élément d’API. Si une fonction est publique, réutilisable, ou destinée à être lue par d’autres développeurs, la docstring a sa place. Si je veux simplement rappeler pourquoi une ligne bizarre existe, un commentaire court suffit.

PEP 257 recommande d’ailleurs d’utiliser des docstrings pour les modules, fonctions, classes et méthodes publiques. En pratique, j’évite de transformer une docstring en mini-manuel: une phrase de synthèse claire, puis quelques lignes si nécessaire, suffisent souvent. Le but n’est pas d’écrire plus, mais d’écrire à la bonne place.

Une fois la frontière posée, il reste le plus important: savoir écrire des commentaires qui valent réellement la peine d’être lus.

Les bonnes pratiques qui rendent les commentaires vraiment utiles

PEP 8 donne un cap assez simple: un commentaire doit être clair, cohérent et à jour. Le point le plus important, à mes yeux, est le suivant: un commentaire qui contredit le code est pire que l’absence de commentaire. Si la logique change, le commentaire doit changer en même temps, sinon il devient un piège silencieux.

• J’explique le pourquoi, pas le quoi.
• Je garde les commentaires courts quand l’idée est simple.
• Je rédige des phrases complètes, avec majuscule et ponctuation quand c’est pertinent.
• J’utilise les commentaires en ligne avec parcimonie, surtout pour une précision vraiment utile.
• Je supprime le code mort plutôt que de laisser des blocs commentés “au cas où”.
• Je fais attention à la langue du projet: dans une équipe internationale, l’anglais reste souvent le choix le plus sûr.

Il y a aussi une règle pratique que je trouve très saine: si le code peut être rendu plus explicite par un meilleur nom de variable, une fonction plus courte ou une structure plus simple, je préfère corriger le code plutôt que le commentaire. Le commentaire n’est pas un pansement pour un code mal conçu.

Dans les projets techniques, notamment ceux qui touchent à l’automatisation, aux données ou à la sécurité, ce réflexe est précieux. Un commentaire utile peut justifier une exception, signaler une hypothèse de confiance ou expliquer pourquoi une vérification existe. Un commentaire vague, lui, ne fait que compliquer l’audit.

Un exemple concret de commentaire bien placé

Voici un cas simple, proche de ce qu’on rencontre dans un script métier: calculer un montant final avec une règle promotionnelle et un arrondi maîtrisé. Je ne commente pas chaque opération. Je commente seulement les choix qui ne sont pas évidents au premier regard.

from decimal import Decimal

VAT = Decimal("0.20")
MINIMUM_FEE = Decimal("4.90")

def compute_total(price, has_coupon=False):
    """Return the final amount to charge for a basket."""

    base = Decimal(price)

    # La remise ne s'applique que si le panier dépasse le seuil promotionnel.
    if has_coupon and base >= Decimal("50"):
        base *= Decimal("0.90")

    # On arrondit seulement à la fin pour éviter les écarts cumulés.
    total = (base * (1 + VAT)) + MINIMUM_FEE
    return total.quantize(Decimal("0.01"))

Ce code fonctionne parce que les commentaires n’énoncent pas l’évidence. Ils expliquent deux règles qui auraient pu être mal interprétées lors d’une relecture: le seuil de remise et le choix d’arrondir à la fin. C’est exactement le genre d’information qu’un lecteur ne devine pas forcément à partir des lignes elles-mêmes.

À l’inverse, un commentaire comme # Multiplie le prix serait inutile, car la ligne le dit déjà. Dans un vrai projet, je préfère deux commentaires précis à dix commentaires décoratifs.

Si je devais garder une seule règle en tête pour commenter du Python proprement, je retiendrais celle-ci: écrire seulement ce qui éclaire une décision, puis le supprimer dès qu’il n’est plus exact. C’est ce réflexe qui garde un code lisible longtemps, pas une accumulation de phrases autour de chaque instruction.

Les trois réflexes que j’applique avant d’ajouter un commentaire

• Je vérifie d’abord si le code peut être rendu plus lisible sans commentaire supplémentaire.
• Je n’écris un commentaire que s’il apporte une information que le lecteur ne peut pas déduire seul.
• Je relis les commentaires à chaque modification de logique, comme je relis le code lui-même.

En pratique, c’est cette discipline qui fait la différence entre un fichier vraiment maintenable et un fichier qui semble explicite seulement au moment où il a été écrit. Si je devais résumer l’approche en une phrase, je dirais qu’un bon commentaire Python doit rester utile même six mois plus tard, quand le contexte initial a déjà disparu.