Les commentaires en Python
Pour avoir un code propre et organisé, facile à maintenir et collaboratif, il est essentiel d'utiliser les commentaires avec Python.
Ce sont des chaînes de caractères qui ne sont pas interprétées par Python.
Syntaxe des commentaires en Python
Le symbole #
C’est le caractère unique de commentaire dans Python. Tout ce qui suit ce symbole sur une ligne est ignoré par l’interpréteur.
# Ceci est un commentaire
x = 42 # Ceci aussiDans cet exemple "Ceci est un commentaire" et "Ceci aussi" ne sont pas interprétés par Python.
Commentaire sur une ligne
Il est possible d'ajouter un commentaire sur une seule ligne en Python : c'est la pratique la plus courante.
# On initialise le compteur à zéro
compteur = 0
Commentaire sur plusieurs lignes
Il est aussi possible de simuler un commentaire sur plusieurs lignes : car il ne s'agit que de plusieurs commentaires monoligne les uns en-dessous des autres.
# Ligne 1
# Ligne 2
# Ligne 3Il est important de ne pas tomber dans le piège d'utiliser un docstring temporaire pour faire des commentaires sur plusieurs lignes. Il s'agit d'une mauvaise pratique : ils sont réservés à la documentation. 😬
PYTHON""" Ce bloc peut servir à désactiver un morceau de code temporairement. """
Bonnes pratiques générales
Un bon commentaire ne doit pas répéter ce que le code dit déjà, mais éclairer ce qu'il ne dit pas.
Pour être sûr de faire un bon commentaire, il convient de suivre quelques petites règles :
- Clair : toujours utiliser un vocabulaire simple et sans superflu (on abandonne les tournures abstraites) ;
- Concis : éviter les paragraphes, aller droit au but ;
- Utile : un commentaire doit toujours avoir une valeur ajoutée.
Par exemple, ceci est un mauvais exemple :
i = 0 # On met i à 0Par contre, celui-ci est beaucoup mieux :
i = 0 # Compteur utilisé pour éviter une boucle infinieCe commentaire indique l’intention du développeur, ce qui n’est pas évident depuis la seule ligne de code.
Commentez l’intention, pas l’implémentation. Le code explique le "comment", le commentaire doit répondre au "pourquoi".
Quand commenter son code ?
Tous les morceaux de code ne nécessitent pas un commentaire. Il faut commenter au bon endroit et pour la bonne raison.
Généralement, un commentaire est justifié quand :
- Le code est complexe ou inhabituel ;
- Une règle métier est appliquée ;
- Une exception technique est faite volontairement (ce qui peut expliquer à la volée un choix technique) ;
- Ou pour une solution temporaire (les fameux commentaires
# TODO : remplacer x par y)
Évitez de commenter des évidences, mais n’hésitez jamais à documenter une décision technique ou un comportement non conventionnel.
Commentaires vs docstrings
Les commentaires et les docstrings remplissent deux fonctions bien distinctes :
| Fonction | Commentaire (#) | Docstring (""") |
| Portée | Ligne, bloc, logique interne | Fonction, classe, module, package, script |
| But principal | Expliquer le code à l'intérieur d'une fonction | Documenter l'usage d'une fonction |
| Visibilité | Pas interprété à l'exécution | Accessible via des outils comme help() ou l'IDE |
| Convention | Libre | Doit respecter la norme PEP 257 |
Les docstrings décrivent ce que fait un objet.
Les commentaires expliquent pourquoi ou comment une chose est faite à l'intérieur d'un objet.
Questions fréquentes sur les commentaires
Les commentaires ralentissent-ils l’exécution du code ?
Non. Les commentaires sont complètement ignorés par l’interpréteur Python.
Un commentaire est-il obligatoire ?
Non. Python ne l’impose pas. Mais la lisibilité de votre code en dépend fortement, surtout en équipe ou pour des projets à long terme.
Comment se former à Python ?
Vous pouvez suivre notre formation sur Python ! 😋