En Python, on ne dispose pas d’un vrai commentaire « multiline » au sens d’une syntaxe dédiée. La bonne approche dépend donc du contexte : expliquer un bloc de code, documenter une fonction, ou laisser une note temporaire sans alourdir le fichier. Je vais vous montrer la méthode correcte, les alternatives utiles et les pièges qui font perdre en lisibilité.
Les points essentiels à retenir avant d’écrire un bloc de commentaires en Python
- Un commentaire Python commence par # et s’arrête à la fin de la ligne.
- Pour plusieurs lignes, on écrit simplement plusieurs lignes de commentaires, chacune avec #.
- Les triples guillemets servent surtout aux docstrings, pas aux commentaires généraux.
- Un bon commentaire explique surtout le pourquoi, pas ce que le code montre déjà.
- PEP 8 recommande des commentaires clairs, complets et bien mis à jour.
Python ne prévoit pas de commentaire multilignes natif
La première chose à clarifier, c’est qu’en Python, un commentaire n’est pas un bloc syntaxique fermé par un marqueur spécial. La règle est simple : un commentaire commence avec # et s’arrête à la fin de la ligne. Si vous voulez commenter plusieurs lignes, vous écrivez donc plusieurs commentaires successifs. C’est la pratique normale, et c’est aussi la plus lisible.
Les triples guillemets, eux, ne créent pas un commentaire. Ils créent une chaîne de caractères. Placée au bon endroit, cette chaîne devient une docstring, c’est-à-dire une documentation attachée à un module, une classe ou une fonction. Ce n’est pas un détail théorique : si vous utilisez des guillemets triples comme simple “bloc de commentaires”, vous mélangez deux usages différents et vous risquez de tromper le lecteur du code.
Autrement dit, la réponse courte à la question est la suivante : il n’existe pas de syntaxe spéciale pour les commentaires sur plusieurs lignes, seulement des commentaires ligne par ligne. La suite consiste donc à choisir la forme la plus propre selon ce que vous voulez expliquer.
La manière la plus propre d’écrire plusieurs lignes de commentaires
Pour annoter un passage de code, je recommande d’écrire un commentaire de bloc avec une ligne par idée, chaque ligne commençant par # et un espace. C’est exactement l’esprit de PEP 8 : un commentaire doit être lisible, complet, et rester au même niveau d’indentation que le code qu’il accompagne.
# Valider les entrées avant le calcul final.
# On garde cette vérification ici parce que la fonction
# peut être appelée depuis plusieurs points du pipeline.
if not payload:
raise ValueError("payload vide")Cette forme fonctionne bien quand vous devez expliquer un choix, une contrainte métier ou une subtilité algorithmique. Si le bloc contient plusieurs paragraphes, on peut les séparer par une ligne contenant uniquement #. Cela reste léger visuellement et évite le faux effet “mur de texte”.
# Préparer les données pour l’export.
#
# On normalise les identifiants pour éviter les écarts
# entre les résultats de l’API et ceux du traitement batch.Je préfère cette méthode aux artifices plus ambigus, parce qu’elle ne change jamais le sens du code. Elle dit simplement au lecteur ce qu’il doit comprendre avant d’exécuter la suite.
Quand une docstring est plus adaptée qu’un commentaire
Si vous documentez une fonction, une classe ou un module, la docstring est souvent le bon outil. Elle se place comme première instruction de l’objet concerné et devient accessible via __doc__, help() ou les générateurs de documentation. C’est précisément le cas d’usage décrit par PEP 257.
def normaliser_identifiant(valeur: str) -> str:
"""Normalise un identifiant avant stockage.
Supprime les espaces superflus et convertit la valeur en minuscules.
"""
return valeur.strip().lower()La différence est importante : une docstring décrit l’interface ou le contrat d’un élément de code, alors qu’un commentaire de bloc explique une décision locale, un contournement, une hypothèse ou un cas particulier. Si vous commentez une fonction publique, la docstring est souvent plus utile qu’un bloc de # dispersé au-dessus de chaque ligne.
Je retiens une règle simple : si l’information doit aider un autre développeur à utiliser la fonction, je vais vers la docstring ; si elle sert à comprendre pourquoi le code est écrit ainsi, je garde le commentaire de bloc. Cette distinction évite beaucoup de bruit inutile.
Choisir entre bloc de commentaires, docstring et faux bloc de texte
Dans la pratique, trois options reviennent souvent. Deux sont légitimes, une troisième est un raccourci trompeur qu’il vaut mieux éviter. Je résume la différence ci-dessous pour vous aider à décider rapidement.
| Technique | Usage idéal | Avantage | Limite |
|---|---|---|---|
Commentaires avec #
|
Expliquer un bloc de logique, un choix métier, un contournement | Clair, explicite, conforme aux conventions Python | À maintenir à jour si le code change |
Docstring avec """..."""
|
Documenter un module, une fonction, une classe ou une méthode | Lisible par les outils et par les humains | Ne doit pas servir à commenter du code interne au hasard |
| Chaîne triple guillemets isolée | Aucun usage recommandé pour commenter du code | Peut sembler rapide à écrire | Ce n’est pas un commentaire, juste une chaîne littérale |
Le point qui piège le plus souvent les débutants, c’est la dernière ligne. On voit parfois un bloc de guillemets triples placé au milieu d’une fonction en pensant “désactiver” temporairement du code. En réalité, on crée un objet chaîne inutile, ce qui n’est ni élégant ni vraiment porteur de sens. Si votre but est de désactiver un morceau de logique, la bonne approche reste souvent de le supprimer, de l’extraire dans une fonction de test ou de le protéger autrement pendant le développement.
Les erreurs qui rendent les commentaires moins utiles
Les commentaires deviennent vite contre-productifs lorsqu’ils répètent simplement ce que le code dit déjà. C’est le cas des remarques du type # incrémente x au-dessus d’un x += 1. Le lecteur voit déjà l’action. Le commentaire n’apporte rien, et il vieillit mal.
- Évitez de commenter l’évidence.
- Évitez les blocs de texte trop longs pour un détail trivial.
- Évitez d’utiliser des triples guillemets comme faux commentaire.
- Évitez les commentaires qui expliquent un état ancien du code.
- Évitez de mélanger un commentaire utile avec une explication trop verbeuse.
Il y a aussi un point technique à ne pas rater : une ligne terminée par un antislash \ ne sert pas à prolonger un commentaire. Dans la grammaire Python, le backslash concerne surtout la continuation explicite d’une instruction, pas l’écriture d’un bloc de commentaires. Si vous voyez une solution qui repose là-dessus, je considère qu’elle est fragile et peu lisible.
Enfin, gardez un œil sur la langue et sur la mise à jour. Un commentaire obsolète est souvent pire que l’absence de commentaire, parce qu’il donne une fausse confiance. Je préfère un code légèrement plus explicite qu’un code très commenté mais incohérent.
La règle simple que j’applique pour garder le code lisible
Quand j’écris ou relis du Python, je pars d’une règle très concrète : le code doit porter l’intention principale, et le commentaire doit seulement combler ce que le code ne peut pas exprimer proprement. En pratique, cela donne trois réflexes. D’abord, utiliser des commentaires de bloc avec # pour les décisions locales. Ensuite, réserver les docstrings à la documentation des objets publics. Enfin, si un commentaire devient trop long, me demander si le code ne devrait pas être refactoré.
Cette discipline change beaucoup de choses, surtout dans les projets qui vivent longtemps. Les commentaires courts, bien placés et à jour font gagner du temps lors d’une relecture, d’un débogage ou d’une reprise de projet. Les blocs flous, eux, finissent par être ignorés. Et c’est exactement ce qu’il faut éviter si vous voulez écrire du Python propre, maintenable et agréable à parcourir.
Si je devais résumer la pratique en une phrase, ce serait celle-ci : en Python, on n’écrit pas un faux commentaire multiline, on choisit entre plusieurs lignes de # et une vraie docstring selon l’objectif réel du texte. C’est simple, robuste, et c’est ce qui sert le mieux le lecteur.
