Commentaires Python — Ligne unique, multi-ligne et bonnes pratiques

Les commentaires sont des lignes dans votre code source que l'interpréteur Python ignore complètement. Ils existent pour les lecteurs humains — pour expliquer l'intention, documenter les décisions et signaler des problèmes — sans affecter l'exécution du programme. Ce chapitre couvre tous les types de commentaires Python, quand utiliser chacun d'eux, et les conventions qui maintiennent la lisibilité des grandes bases de code.

Commentaires sur une seule ligne

Un commentaire sur une seule ligne commence par le caractère dièse (#). Tout ce qui suit le # jusqu'à la fin de cette ligne est ignoré par l'interpréteur.

# Calculate the area of a circle
radius = 5
area = 3.14159 * radius ** 2
print(area)  # outputs 78.53975

Le commentaire sur la dernière ligne — placé après du code exécutable sur la même ligne — est appelé un commentaire inline. Utilisez-les avec parcimonie ; réservez-les pour une logique véritablement non évidente plutôt que de répéter ce que le code dit déjà.

Quand utiliser les commentaires sur une seule ligne

• Expliquer pourquoi une décision a été prise, pas ce que fait le code (le code montre le quoi).
• Marquer des contournements temporaires : # TODO: replace with database lookup.
• Désactiver temporairement une seule ligne pendant le débogage.

# FIXME: division by zero if user_count is 0
average = total_score / user_count

Commentaires multi-lignes

Python ne dispose pas de syntaxe de commentaire multi-ligne dédiée comme le fait C avec /* ... */. La façon idiomatique de s'étendre sur plusieurs lignes est d'utiliser des commentaires consécutifs sur une seule ligne, chacun commençant par #.

# This function converts a temperature in Celsius to Fahrenheit.
# The formula is: F = (C * 9/5) + 32
# Returns a float rounded to two decimal places.
def celsius_to_fahrenheit(c):
    return round((c * 9 / 5) + 32, 2)

print(celsius_to_fahrenheit(100))  # 212.0
print(celsius_to_fahrenheit(0))    # 32.0

La plupart des éditeurs Python et des IDE vous permettent de sélectionner plusieurs lignes et de basculer # sur toutes en même temps (généralement Ctrl+/ ou Cmd+/).

Docstrings — commentaires de documentation structurés

Python dispose d'une convention de littéral de string spéciale appelée docstring (abréviation de documentation string). Une docstring est une string entre triple guillemets placée immédiatement après un en-tête def, class ou module. Bien que techniquement une expression string et non un commentaire, elle sert de mécanisme de documentation standard et est accessible à l'exécution via l'attribut __doc__.

def greet(name):
    """Return a personalised greeting message.

    Args:
        name (str): The name of the person to greet.

    Returns:
        str: A greeting string.
    """
    return f"Hello, {name}!"

print(greet("Alice"))        # Hello, Alice!
print(greet.__doc__)         # prints the docstring above

Strings entre triple guillemets comme commentaires de bloc

Parce que Python ignore les littéraux de string qui ne sont pas assignés à quoi que ce soit, une string entre triple guillemets seule (pas dans une position def/class) est parfois utilisée comme commentaire de bloc informel :

"""
This script processes the daily sales report.
It reads from sales.csv, aggregates by region,
and writes a summary to report.txt.
"""

import csv

Ce motif fonctionne mais a un coût subtil : contrairement aux commentaires #, l'interpréteur analyse bien la string et peut la conserver dans le bytecode compilé. Pour la documentation au niveau du module, préférez une docstring de module appropriée (la toute première instruction du fichier). Pour d'autres explications multi-lignes à l'intérieur des fonctions, tenez-vous-en à des lignes # consécutives.

Commenter du code pendant le débogage

Désactiver temporairement du code avec des commentaires est une technique de débogage courante :

def calculate_discount(price, rate):
    # discount = price * rate        # old flat-rate formula
    discount = price * rate if rate < 1 else price * (rate / 100)
    return price - discount

print(calculate_discount(100, 0.2))   # 80.0
print(calculate_discount(100, 20))    # 80.0

Une fois que vous avez confirmé le correctif, supprimez les lignes commentées plutôt que de les laisser définitivement dans la base de code — du code commenté obsolète perturbe les futurs lecteurs.

Directives de commentaires spéciales

Python et ses outils reconnaissent quelques lignes de commentaires qui ont une signification lisible par machine :

La ligne shebang

Sur les systèmes de type Unix, la première ligne d'un script peut spécifier l'interpréteur :

#!/usr/bin/env python3
# This line tells the OS to run the file with python3.

print("Hello from a standalone script!")

Cette ligne est un commentaire du point de vue de Python (elle commence par #), mais le système d'exploitation l'utilise lorsque le fichier est exécuté directement (./script.py).

Déclaration d'encodage

Si votre fichier source utilise un encodage de caractères autre que UTF-8 (la valeur par défaut depuis Python 3), déclarez-le sur la première ou la deuxième ligne :

# -*- coding: utf-8 -*-

Python 3 utilise par défaut UTF-8, donc cela est rarement nécessaire aujourd'hui, mais vous pouvez le rencontrer dans du code legacy.

Directives pour les vérificateurs de types

Les vérificateurs de types tels que mypy respectent des commentaires inline spéciaux :

x = []  # type: ignore
result = some_function()  # type: ignore[return-value]

Ceux-ci suppriment des erreurs de type spécifiques sans changer le comportement à l'exécution. Consultez le chapitre Variables Python pour en savoir plus sur la façon dont Python gère les types.

Bonnes pratiques pour les commentaires

Suivre ces conventions rendra vos commentaires véritablement utiles :

PEP 8 — le guide de style officiel de Python — recommande :

• Les commentaires inline doivent être séparés de l'instruction par au moins deux espaces.
• Chaque commentaire inline doit commencer par # (dièse, puis un espace).
• Les commentaires de bloc qui s'appliquent au code en dessous doivent être indentés au même niveau.

def apply_tax(price, tax_rate):
    # Tax rate is expressed as a decimal (e.g., 0.07 for 7 %).
    # Prices must be non-negative; validation happens upstream.
    tax = price * tax_rate
    return price + tax  # total including tax

Erreurs courantes à éviter

1. Laisser des commentaires TODO sans les suivre

# TODO: handle the case where the file does not exist
data = open("data.txt").read()

Les TODO sont utiles pendant le développement mais doivent être liés à un outil de suivi des problèmes, et non laissés indéfiniment dans le code de production.

2. Commenter de grands blocs au lieu de les supprimer

Le contrôle de version (git) préserve l'historique. Il n'est pas nécessaire de conserver du code commenté pour la postérité — supprimez-le et comptez sur git log si vous en avez besoin.

3. Style incohérent

Un mélange de #comment, # comment et ## comment dans le même fichier donne l'impression que la base de code n'est pas maintenue. Convenez d'un style et appliquez-le de manière cohérente.

Résumé

Les commentaires sont un outil léger qui porte ses fruits chaque fois qu'un autre développeur (ou vous dans le futur) lit votre code. Pour approfondir les sujets connexes, consultez Syntaxe Python et Variables Python.

Pratique