Commentaires Python : ligne unique, multilignes et docstrings

Les commentaires sont pour les humains

Python ignore les commentaires. C'est toute l'astuce. Tout ce que tu marques comme commentaire est invisible pour l'interpréteur — c'est là uniquement pour la personne qui lit ton code, qui est généralement le toi du futur, dans six mois, à se demander ce que le toi du passé avait en tête.

Cela dit, un commentaire qui ne fait que répéter ce que le code fait de façon évidente ne vaut pas la peine d'être écrit. Les meilleurs commentaires expliquent pourquoi — une contrainte, un contournement, une décision qui n'est pas évidente depuis le code lui-même. Le code te dit déjà quoi il se passe.

Commentaires sur une seule ligne avec #

La forme de base, c'est un # suivi de ta note :

Tu peux aussi ajouter un court commentaire en fin de ligne. Par convention, laisse au moins deux espaces avant le # :

Python lit un # n'importe où en dehors d'une chaîne et traite le reste de la ligne comme un commentaire. Ce « en dehors d'une chaîne » compte : # à l'intérieur de guillemets est juste un caractère.

Le #section-2 à l'intérieur de la chaîne fait partie de l'URL. Python ne bascule en mode « commentaire » que pour le # après la fermeture de la chaîne.

Commenter plusieurs lignes

Python n'a pas de commentaire de bloc /* */. Pour sauter plusieurs lignes, mets # au début de chacune :

Tu ne tapes presque jamais ces # à la main. Chaque éditeur digne de ce nom a un raccourci « toggle line comment » qui ajoute ou retire # sur chaque ligne sélectionnée :

• VS Code : Cmd + / (macOS) ou Ctrl + / (Windows/Linux)
• PyCharm : Cmd + / ou Ctrl + /
• Vim : dépend de tes plugins ; vim-commentary associe gcc pour une seule ligne et gc pour une sélection.

Apprends le raccourci dans ton éditeur une fois, et « commenter ce bloc pour essayer quelque chose » devient une opération à une seule touche.

L'astuce de la chaîne à triple guillemets (et pourquoi ce n'est pas un vrai commentaire)

Tu verras parfois du code comme ça :

Techniquement, c'est une expression chaîne qui est jetée. Python la parse, l'évalue et jette le résultat. Elle se comporte comme un commentaire, mais ce n'en est pas un. Stylistiquement, c'est une bonne idée seulement dans un cas précis : comme docstring.

Docstrings : le seul endroit où les triples guillemets ont leur place

Une docstring est une chaîne à triple guillemets placée comme toute première instruction dans une fonction, une classe ou un module. Python la reconnaît comme documentation et la rend disponible à l'exécution via la fonction help() et l'attribut __doc__ :

Deux choses rendent les docstrings agréables :

1. Des outils comme les IDE, help() et les générateurs de documentation les lisent automatiquement. Un commentaire au-dessus de la fonction n'a rien de tel.
2. Elles décrivent la fonction à l'endroit de l'appel — quand quelqu'un survole discount(...) dans son éditeur, la docstring apparaît en infobulle.

Il y a une convention (PEP 257) pour ce qui va dans une docstring : un résumé d'une ligne sur la première ligne, une ligne vide, puis une description plus longue si nécessaire. Ne stresse pas sur le format exact dès le premier jour — une simple ligne vaut toujours bien mieux qu'aucune docstring.

Ce que disent vraiment les bons commentaires

Quelques lignes directrices qui épargnent beaucoup de soucis plus tard :

• Préfère décrire le pourquoi plutôt que le quoi. # Loop over the users est du bruit ; # Retry on 503 — Redis sometimes dies mid-deploy vaut de l'or.
• Mets à jour les commentaires quand tu changes le code. Un mauvais commentaire est pire qu'aucun commentaire. Les commentaires obsolètes induisent activement en erreur les futurs lecteurs.
• Ne commente pas du code et ne le laisse pas traîner. Si tu n'en as pas besoin, supprime-le. Le contrôle de version se souvient. Un fichier parsemé de blocs commentés devient rapidement peu fiable.
• Saute l'évident. x = x + 1 # increment x n'apporte rien.

En résumé

Les commentaires sont gratuits à écrire et peu coûteux à sauter. Sers-t'en quand tu laisses une note qu'un lecteur te remerciera d'avoir laissée — une raison subtile pour laquelle quelque chose fonctionne, un lien vers un ticket, un avertissement sur un cas limite. Utilise les docstrings quand tu définis une fonction ou une classe. Sinon, laisse des noms clairs et de petites fonctions parler à ta place.

Tu as maintenant tout ce qu'il faut pour lire et écrire un fichier Python. Le prochain chapitre, c'est là où le langage commence vraiment à faire des choses : variables, types de données et les valeurs que Python peut contenir.