Commentaires

Python

En Python, un commentaire commence par # en dehors d’une chaîne et se termine à la fin de la ligne. Pour commenter plusieurs lignes, placez # sur chacune. Les triples guillemets créent une chaîne, éventuellement utilisée comme docstring, et ne constituent pas une syntaxe de commentaire.

Commentaire de ligne et # dans une chaîne

Un commentaire ordinaire explique les intentions ou les conditions du code et son contenu est ignoré lors de l’analyse syntaxique. Il peut occuper toute une ligne ou suivre une instruction. Consultez les règles officielles des commentaires Python pour connaître sa portée exacte.

Les exemples nécessitent seulement Python 3. Enregistrez chaque exemple complet dans comments_example.py en UTF-8 et lancez python comments_example.py, ou python3 selon votre installation. Remplacez le contenu du fichier pour essayer un autre exemple indépendamment.

# Calculate the total before discounts.
price = 100
quantity = 2  # Number of items
print(price * quantity)

Résultat attendu :

Entre guillemets, # fait partie du texte. Il ne coupe donc ni une phrase ni le fragment d’une URL :

print("# This is part of a string")
print("https://example.com/page#section")

# This is part of a string
https://example.com/page#section

Commenter chaque ligne d’une explication longue

Python ne propose pas de commentaire de bloc distinct comparable à /* ... */ en C. Marquez chaque ligne et alignez son indentation avec le code qu’elle décrit pour rendre leur relation claire.

# The sample uses a fixed discount rate.
# Production rules may depend on the customer.
base_price = 100
discount_rate = 0.1
print(base_price * (1 - discount_rate))

90.0

Pour désactiver temporairement du code, commentez ses lignes, puis retirez les marqueurs pour le réactiver. Les éditeurs automatisent généralement cette opération avec une commande de commentaire multiligne. Conservez les anciennes implémentations dans l’historique des versions plutôt que d’accumuler des variantes commentées dans le fichier.

Triples guillemets et docstrings sont des chaînes

Trois guillemets simples ou doubles délimitent un littéral de chaîne pouvant contenir plusieurs lignes. Placé comme première instruction d’un module, d’une classe ou d’une fonction, ce littéral devient une docstring, accessible par __doc__ et les outils d’aide. La documentation des docstrings détaille ce rôle.

def greet(name):
    """Return a greeting for name."""
    return f"Hello, {name}"

print(greet("Ada"))
print(greet.__doc__)

Hello, Ada
Return a greeting for name.

Cette valeur documente la fonction et reste consultable, contrairement à une simple explication en commentaire. La même notation peut aussi stocker de véritables données :

notes = """first line
second line"""
print(notes.splitlines())

['first line', 'second line']

Entourer du code de triples guillemets ne le transforme pas en véritable commentaire. Des guillemets identiques dans son contenu peuvent casser la syntaxe, et sa position peut en faire une docstring. Utilisez # pour désactiver des lignes de code.

Un bloc contenant seulement des commentaires nécessite une instruction

Les blocs introduits par def, if et des constructions similaires doivent contenir une instruction réelle. Un commentaire ne compte pas ; un bloc uniquement commenté peut donc provoquer IndentationError. L’instruction pass, sans effet, sert de réservation.

source = "def todo():\n    # Implement later\n"
try:
    compile(source, "example", "exec")
except IndentationError:
    print("IndentationError")

def todo():
    # Implement later
    pass

print(todo())

IndentationError
None

La première partie compile volontairement du code invalide stocké dans une chaîne et intercepte l’erreur pour poursuivre l’exemple. La fonction suivante est valide grâce à pass. Sans retour explicite, son appel renvoie None.

Explications utiles et directives particulières

PEP signifie Python Enhancement Proposal. Les recommandations de PEP 8 sur les commentaires mettent en garde contre les commentaires qui contredisent le code. Expliquez les choix, contraintes externes et conditions importantes plutôt que les actions évidentes, et actualisez les commentaires lors des modifications. Un commentaire en fin de ligne est habituellement précédé d’au moins deux espaces et suivi d’une espace après #.

Certains commentaires ont une signification pour les outils ou la lecture des fichiers. Une déclaration d’encodage valide sur la première ou deuxième ligne peut influer sur cette lecture ; Python 3 utilise UTF-8 par défaut. Distinguez les directives de linters ou de vérificateurs de types des explications ordinaires et examinez les avertissements avant de les masquer globalement.

Python