Les commentaires en Python ne servent pas à meubler le code, mais à lever une ambiguïté: pourquoi une règle existe, pourquoi une valeur a été choisie, pourquoi une exception est volontaire. Bien utilisés, ils accélèrent la relecture, réduisent les erreurs de maintenance et rendent le travail en équipe beaucoup plus fluide. Mal utilisés, ils ajoutent du bruit et vieillissent souvent plus vite que le code lui-même.
L’essentiel pour écrire un Python lisible et durable
- Un commentaire commence par # et n’est pas exécuté par Python.
- Je l’emploie surtout pour expliquer le pourquoi, pas pour répéter ce que la ligne dit déjà.
- Les docstrings documentent les modules, fonctions, classes et méthodes publiques; elles ne remplacent pas un commentaire local.
- Les commentaires trop nombreux signalent souvent un problème de nommage, de structure ou de découpage du code.
- Certains commentaires sont destinés aux outils, comme les type checkers ou les linters, mais ce sont des cas particuliers.
Les commentaires Python servent à expliquer l’intention
La documentation officielle de Python rappelle qu’un commentaire commence par #, qu’il s’arrête à la fin de la ligne et qu’il est ignoré par l’analyse syntaxique. Autrement dit, le commentaire n’influence pas l’exécution: il sert au lecteur, pas à l’interpréteur. C’est précisément pour cela que je le réserve aux informations qui ne ressortent pas naturellement du code.
Dans un projet réel, cette nuance change tout. Une ligne comme total += frais est compréhensible toute seule. En revanche, si frais représente une exception métier, une règle fiscale ou un contournement temporaire, le commentaire devient utile parce qu’il raconte la raison du choix. Je préfère toujours un commentaire court et précis à une explication longue qui répète l’évidence.
Il faut aussi garder en tête une limite importante: un commentaire peut devenir faux. Un code clair peut survivre à une refactorisation; un commentaire oublié, lui, continue à mentir. C’est pour cela que je traite les commentaires comme une aide de contexte, jamais comme une source de vérité autonome. Une fois cette base posée, il devient plus simple de distinguer ce qui mérite vraiment d’être écrit.
Écrire des commentaires utiles sans alourdir le fichier
Je vois souvent deux excès opposés: des fichiers entièrement commentés, et des fichiers sans aucune indication sur les décisions techniques. Entre les deux, il existe une zone saine, assez simple à viser. Le bon réflexe consiste à commenter ce qui n’est pas immédiatement devinable à la lecture, puis à supprimer tout ce qui ne fait que paraphraser le code.
Commente le pourquoi, pas le comment
Si le code dit déjà clairement ce qu’il fait, le commentaire doit ajouter une couche d’intention. Par exemple:
# On garde une marge pour absorber les pics de trafic
cache_ttl = 45
# Mauvais: le commentaire répète l’évidence
i += 1 # Incrémente iLe premier commentaire apporte une information de contexte. Le second n’apporte rien, car la ligne se suffit à elle-même. C’est une bonne règle de tri: si je peux supprimer le commentaire sans perdre d’information utile, il est probablement superflu.
Reste proche de la zone de code concernée
Un commentaire utile doit être placé là où la décision se lit. Le lecteur ne doit pas remonter trois écrans plus haut pour comprendre ce qu’il explique. En pratique, je préfère un commentaire bref juste au-dessus de la ligne concernée plutôt qu’un bloc de prose éloigné de la logique qu’il décrit.
Lire aussi : Python global - Éviter les pièges des variables globales
Garde un ton factuel
Les commentaires ambiguës, humoristiques ou trop vagues vieillissent mal. Une formule comme # magouille temporaire n’aide personne dans six mois. À la place, j’écris ce qui est réellement vrai: # Contournement nécessaire à cause de l’API X qui renvoie null sur les comptes inactifs. La précision évite les malentendus et facilite les corrections futures.
Quand cette discipline devient naturelle, la vraie question n’est plus seulement “quoi commenter”, mais aussi “quel type de note utiliser”. C’est là que la différence entre commentaire, docstring et nommage devient importante.
Différencier commentaire, docstring et nommage
Dans un code Python propre, ces trois outils ne se remplacent pas: ils se complètent. Je les pense comme trois niveaux d’explication différents. Le nom d’une variable éclaire la donnée, la docstring documente l’API, et le commentaire local explique une décision ponctuelle ou un détail de contexte.
| Élément | Rôle | Quand je l’utilise | Limite |
|---|---|---|---|
| Nom d’identifiant | Rendre le code explicite par lui-même | Pour variables, fonctions, classes et constantes | Ne peut pas expliquer une décision métier complexe |
| Commentaire | Justifier un choix, signaler une contrainte, documenter un cas particulier | Pour un contournement, une règle métier non évidente, un rappel de maintenance | Ne doit pas répéter le code ni remplacer une API lisible |
| Docstring | Documenter le comportement public d’un module, d’une fonction, d’une classe ou d’une méthode | Quand une fonction doit être comprise sans ouvrir son corps | Ce n’est pas un commentaire local; elle décrit l’interface, pas chaque ligne |
| Commentaire d’outil | Communiquer avec un type checker, un linter ou un outil de couverture | Quand l’outillage impose une exception ciblée | Doit rester rare et justifié, sinon il masque des problèmes réels |
La distinction la plus importante, à mes yeux, est celle entre commentaire et docstring. Une docstring fait partie de la documentation du code, alors qu’un commentaire accompagne la lecture locale d’une section précise. La première décrit ce que l’objet expose à l’extérieur; le second explique un détail interne ou une décision temporaire. Si je me trompe de niveau, le texte devient vite confus.
Un autre piège courant consiste à utiliser une chaîne triple guillemets comme faux commentaire. En Python, une string qui n’est pas placée au bon endroit reste une string, pas un commentaire. Pour documenter une fonction publique, j’utilise une vraie docstring; pour expliquer un choix ponctuel, j’utilise un commentaire avec #. Cette séparation évite beaucoup de malentendus.
Des exemples concrets qui aident vraiment en équipe
Dans un contexte de production, je vois surtout quatre cas où un commentaire vaut vraiment la peine d’exister. Le plus utile n’est pas celui qui décrit la mécanique, mais celui qui transmet une information que le lecteur ne peut pas déduire seul.
- Une règle métier non évidente — utile quand un montant, un seuil ou une condition dépend d’une contrainte métier extérieure au code.
- Un contournement temporaire — utile quand une bibliothèque ou une API impose un comportement imparfait que je dois absorber proprement.
- Une décision d’architecture — utile quand le code pourrait être écrit autrement, mais qu’un compromis a été choisi pour la maintenabilité ou la performance.
- Un TODO contextualisé — utile seulement s’il indique quoi faire, pourquoi, et idéalement dans quel délai ou sous quelle condition.
# Le fournisseur facturera le mois entamé; on arrondit donc au jour supérieur
jours_factures = math.ceil(duree_heures / 24)
# Contournement de l'API externe: elle renvoie parfois une chaîne vide au lieu de None
email = email or None
# Cette vérification reste ici parce que le calcul est réutilisé par deux appels différents
if not abonnement_actif:
raise PermissionError("Abonnement inactif")Ces exemples sont intéressants parce qu’ils montrent un détail simple: le commentaire ne remplace pas le code, il donne le contexte qui explique pourquoi le code est écrit ainsi. C’est exactement le niveau d’information qui manque le plus souvent lors des relectures. Un lecteur pressé peut comprendre la ligne, mais il ne devinera pas toujours la contrainte derrière.
Je conseille aussi de garder une discipline de durée. Un TODO sans responsable ni horizon devient vite un dépôt de dettes invisibles. Si je laisse une note de ce type, j’essaie de la rendre exploitable: quoi faire, pourquoi c’est bloquant, et ce qui déclenche sa suppression. Sinon, elle finit par se transformer en bruit permanent.
Les erreurs que je vois le plus souvent
Les mauvais commentaires ne sont pas seulement inutiles; ils peuvent aussi induire une mauvaise lecture du code. Dans une équipe, c’est souvent plus coûteux qu’une absence de commentaire, parce que le lecteur croit avoir une information fiable alors qu’elle ne l’est plus.
| Erreur | Effet | Correction pratique |
|---|---|---|
| Commenter chaque ligne | Le fichier devient lourd et infantilisant | Supprimer les explications évidentes et renforcer les noms |
| Laisser un commentaire périmé | Le lecteur se trompe sur la logique réelle | Mettre à jour le commentaire en même temps que le code, ou le retirer |
| Écrire un commentaire trop vague | Il n’explique ni la cause ni la décision | Nommer la contrainte, la raison ou l’exception concernée |
| Réécrire le code en mots | Double maintenance sans valeur ajoutée | Réserver le commentaire à l’intention, pas à la mécanique |
| Utiliser une note “temporaire” sans suivi | La dette technique s’installe | Associer un responsable, une date ou une condition de suppression |
Je fais aussi attention aux commentaires qui cherchent à compenser un code mal nommé. Si une fonction s’appelle process() et qu’un commentaire doit tout expliquer, le vrai problème est souvent ailleurs. Renommer, découper ou extraire une fonction coûte parfois moins cher que conserver une explication longue et fragile. Le commentaire devient alors le symptôme d’un défaut de conception, pas une solution.
Le dernier piège, plus discret, consiste à traduire toute la base de code en prose. Sur un projet long, la lisibilité vient d’abord de la structure, pas de la quantité de texte autour. Quand un commentaire ne fait pas gagner de clarté, je le supprime sans hésiter.
Les commentaires techniques que les outils comprennent
Dans l’écosystème Python, certains commentaires ont un rôle particulier parce qu’ils sont lus par des outils annexes. Ils ne relèvent pas de la logique métier, mais de la qualité de code, de l’analyse statique ou du packaging. Je les traite comme des exceptions utiles, pas comme une habitude générale.
-
# type: ignorepeut servir avec des outils de typage statique quand une ligne doit être exemptée de vérification. -
# noqaest souvent compris par des linters pour ignorer une alerte précise sur une ligne. -
# pragma: no coverest utilisé dans certaines chaînes de couverture de tests pour exclure un morceau de code. - La déclaration d’encodage en première ou deuxième ligne est un cas spécial de commentaire que Python sait interpréter dans certains contextes.
Le point important, ici, n’est pas de mémoriser chaque mot-clé, mais de comprendre leur statut: ce sont des conventions d’outils, pas des invitations à masquer des problèmes. Si un commentaire technique devient trop fréquent, j’y vois généralement un signal d’alarme. Soit la règle de qualité est trop stricte pour le cas traité, soit le code mérite d’être refactorisé, soit la justification n’est pas assez précise.
Je recommande aussi de documenter ces exceptions au niveau de l’équipe. Sans règle commune, un projet finit vite avec trois styles différents pour la même intention. Une convention courte, claire et partagée évite beaucoup d’allers-retours pendant les revues.
Le filtre que j’utilise avant de laisser une note dans le code
Avant d’ajouter un commentaire, je passe mentalement par une vérification simple. Si le texte ne franchit pas ce filtre, je préfère réécrire le code plutôt que d’ajouter une explication qui vieillira mal.
- Le code est-il déjà assez clair sans commentaire?
- Le commentaire explique-t-il une décision, une contrainte ou un contournement réel?
- Est-il encore vrai dans trois mois, quand le contexte aura changé?
- Peut-on obtenir la même clarté avec un meilleur nom, une fonction plus petite ou une structure plus lisible?
- Le commentaire apporte-t-il une information que le lecteur ne peut pas déduire du code lui-même?
Si la réponse est “non” à plusieurs de ces points, je m’abstiens. C’est une habitude simple, mais elle change beaucoup la qualité d’un dépôt sur la durée. Les bons commentaires rendent un projet plus facile à reprendre; les mauvais créent une illusion de clarté qui se dissout au premier changement important. Dans un code Python bien entretenu, je cherche moins de texte, mais plus d’intention.
Au fond, les meilleurs commentaires sont ceux qui disparaissent presque à la lecture: ils donnent juste assez de contexte pour comprendre vite, puis laissent le code faire le reste.
