Commentaires en Python

1. Comment écrire des commentaires

En Python, comme dans beaucoup d'autres langages de programmation, tu peux écrire des commentaires dans ton code.

Les commentaires, ce n'est que du texte pour d'autres développeurs : l'interpréteur Python ne les regarde même pas et n'exécute pas le code qui s'y trouve. Les commentaires aident les développeurs et d'autres membres du projet à comprendre le code, ce qui est particulièrement utile pour le travail en équipe et la maintenance à long terme des programmes. En Python, il existe plusieurs façons d'ajouter des commentaires dans le code.

Commentaires sur une seule ligne :

Ils commencent par le symbole #. Tout ce qui suit le # sur la même ligne est ignoré par l'interpréteur Python. Ce type de commentaires est généralement utilisé pour des remarques brèves ou des explications sur une ligne de code spécifique. Exemple :

# Ceci est un commentaire sur une seule ligne
print("Hello, World!")  # Explication sur l'action de la fonction

Commentaires sur plusieurs lignes :

En Python, il n'existe pas de syntaxe spéciale officielle pour les commentaires sur plusieurs lignes, mais tu peux les créer à l'aide de plusieurs commentaires sur une ligne ou utiliser des guillemets triples, bien que ces derniers soient en fait des littéraux de chaîne de caractères sur plusieurs lignes, qui ne sont pas exécutés comme du code. Exemple :

# Ceci est un exemple de commentaire sur plusieurs lignes
# Chaque ligne commence par le symbole `#`

ou :

""" Ceci est un littéral sur plusieurs lignes que tu peux utiliser comme un commentaire. Python l'interprète comme une chaîne, mais il ne fait rien de cette chaîne si elle n'est pas assignée à une variable ou utilisée dans une expression. """

Pratique ! Un littéral, c'est juste un petit morceau de données écrit directement dans le code : un nombre, une chaîne, et ainsi de suite.

2. Pourquoi écrire des commentaires

Utiliser des commentaires dans le code le rend plus lisible, facilite sa maintenance et ses mises à jour, et améliore aussi la collaboration en équipe. Les commentaires doivent être courts, mais informatifs et pertinents, pour servir de documentation utile au code sans l'encombrer d'informations superflues.

Les strings documentaires (docstrings):

Ce sont des chaînes de caractères sur plusieurs lignes qui se trouvent généralement au début des modules, classes, méthodes et fonctions pour décrire leur but. Elles sont encadrées par trois paires de guillemets doubles et utilisées pour générer automatiquement de la documentation.

Exemple :

def add(a, b): """ Fonction pour additionner deux nombres. :param a: premier terme :param b: second terme :return: somme de a et b """ return a + b 

Dans le monde de la programmation, les développeurs ajoutent parfois à leur code des commentaires qui non seulement expliquent, mais font sourire. Voici quelques exemples de commentaires amusants que tu peux croiser dans le code :

Exemple 1 :

# J'expliquerais bien ce qui se passe ici, mais moi-même je ne comprends plus.

Exemple 2 :

# Si ça ne marche pas, c'est la faute de quelqu'un d'autre.

Exemple 3 :

# Veni, vidi, corrigé... et cassé.

Exemple 4 :

# Quand j'ai écrit ça, seul Dieu et moi savions comment ça marche.
# Maintenant, seul Dieu le sait.

Exemple 5 :

# Nombre d'heures perdues ici = 42.

Ces commentaires peuvent ajouter une touche de légèreté et d'humour au processus de développement, rendant la base de code un peu moins monotone. Ils rappellent aussi que le développement logiciel est un processus créatif et humain.

5.3 Commenter rapidement du code

Dans l'IDE PyCharm, tu peux rapidement commenter ou décommenter du code en utilisant des raccourcis clavier. Pour cela, sélectionne les lignes de code que tu veux commenter ou décommenter, et appuie sur Ctrl + / sous Windows (ou Cmd + / sous macOS). Cette combinaison de touches ajoute ou enlève le symbole de commentaire sur toutes les lignes sélectionnées, rendant ce processus rapide et efficace.