Ajouter des Commentaires en Python

Introduction

Dans ce laboratoire, vous apprendrez l'importance et l'application pratique des commentaires en Python. Les commentaires sont essentiels pour rendre votre code compréhensible, ce qui est crucial pour la maintenance et la collaboration. Vous explorerez différents types de commentaires, y compris les commentaires sur une seule ligne et les commentaires sur plusieurs lignes, et apprendrez à les utiliser efficacement pour améliorer la lisibilité du code.

Comprendre l'Objectif des Commentaires

Les commentaires sont des notes dans votre code qui sont ignorées par l'interpréteur Python mais qui sont précieuses pour les lecteurs humains. Ils aident à expliquer la logique du code, son objectif et tout détail non évident. Bien qu'une machine exécute le code, ce sont les humains qui doivent le lire et le maintenir. De bonnes habitudes de commentaire sont essentielles pour écrire des programmes clairs et compréhensibles.

Commençons par un script simple sans aucun commentaire. Dans l'environnement WebIDE, localisez le fichier purpose.py dans l'explorateur de fichiers du panneau de gauche et ouvrez-le.

Ajoutez le code suivant dans le fichier purpose.py :

x = 10
y = 20
z = x + y
print(z)

Enregistrez le fichier en appuyant sur Ctrl + S.

Pour exécuter le script, ouvrez le terminal intégré dans l'environnement WebIDE en naviguant vers le menu supérieur et en sélectionnant Terminal -> New Terminal. Le terminal s'ouvrira en bas de l'écran, et le chemin par défaut est ~/project.

Exécutez le script en lançant la commande suivante dans le terminal :

python purpose.py

Vous verrez le résultat du calcul :

30

Ce script est simple, mais dans un programme plus vaste, il n'est pas immédiatement clair ce que représentent x, y et z. Dans l'étape suivante, nous ajouterons des commentaires pour rendre ce code plus facile à comprendre.

Utiliser les Commentaires sur une Seule Ligne

Les commentaires sur une seule ligne sont utilisés pour des notes courtes et explicatives. En Python, un commentaire sur une seule ligne commence par le symbole dièse (#). L'interpréteur ignore tout ce qui suit le # sur cette ligne. Ces commentaires peuvent être placés sur une ligne séparée pour décrire le code ci-dessous ou sur la même ligne qu'une instruction pour l'expliquer.

Modifions le fichier purpose.py pour y inclure des commentaires sur une seule ligne. Ouvrez purpose.py dans l'éditeur et mettez à jour son contenu comme suit :

## This script calculates the sum of two numbers

x = 10  ## Assign the integer 10 to variable x
y = 20  ## Assign the integer 20 to variable y
z = x + y  ## Calculate the sum of x and y
print(z) ## Print the final result to the console

Enregistrez le fichier (Ctrl + S) et exécutez-le à nouveau depuis le terminal :

python purpose.py

Le résultat sera le même qu'auparavant :

30

Comme vous pouvez le constater, les commentaires n'ont pas modifié le comportement du programme. Cependant, le code est maintenant beaucoup plus lisible. Le premier commentaire explique l'objectif général du script, tandis que les commentaires en ligne clarifient le rôle de chaque ligne.

Utiliser les Commentaires Multi-Lignes

Pour des explications plus longues qui s'étendent sur plusieurs lignes, vous pouvez utiliser le format de commentaire sur plusieurs lignes. Bien que Python n'ait pas de syntaxe spécifique pour les commentaires sur plusieurs lignes comme certains autres langages, vous pouvez utiliser des chaînes de caractères multi-lignes (multi-line strings) à cette fin.

Une chaîne de caractères multi-lignes est créée en entourant le texte de triples guillemets, soit """...""" (doubles) soit '''...''' (simples). Si cette chaîne multi-lignes n'est pas assignée à une variable, l'interpréteur Python l'ignorera, la transformant ainsi effectivement en commentaire. C'est une convention courante pour écrire des commentaires de bloc ou la documentation de fonctions (docstrings).

Trouvez et ouvrez le fichier multiline.py dans l'environnement WebIDE. Ajoutez le code suivant :

"""
This is a multi-line comment using triple double quotes.
This script demonstrates how to write comments that span
several lines to provide more detailed explanations.
"""

message = "Hello, Python learners!"
print(message)

Enregistrez le fichier et exécutez-le depuis le terminal :

python multiline.py

Vous verrez la sortie suivante :

Hello, Python learners!

Le bloc de texte entre les triples guillemets a été ignoré, et seule l'instruction print a été exécutée. Cette technique est très utile pour fournir des descriptions détaillées au début d'un fichier ou avant une fonction complexe.

Utiliser les Commentaires de Déclaration

Python prend également en charge des commentaires spéciaux appelés commentaires de déclaration (declaration comments). Ceux-ci sont traités par l'interpréteur ou le système d'exploitation pour configurer la manière dont le script s'exécute. Deux exemples courants sont le shebang et la déclaration d'encodage.

1. Shebang (#!): La ligne shebang est la toute première ligne d'un script. Elle indique à un système d'exploitation de type Unix quel interpréteur utiliser pour exécuter le fichier. Pour un script Python 3, il s'agit généralement de #!/usr/bin/python3. Cela vous permet d'exécuter le script comme un exécutable autonome.

2. Déclaration d'Encodage (Encoding Declaration): Ce commentaire indique à l'interpréteur Python quel encodage de caractères utiliser pour le fichier source. C'est important si votre code contient des caractères non-ASCII. La déclaration standard pour UTF-8 est ## -*- coding: utf-8 -*-. Elle doit être placée sur la première ou la deuxième ligne du fichier.

Créons un script qui utilise les deux. Ouvrez le fichier declaration.py dans l'éditeur et ajoutez le code suivant :

#!/usr/bin/python3
## -*- coding: utf-8 -*-

## This script demonstrates declaration comments and non-ASCII characters.
print("Hello, World!")
print("你好，世界！") ## A greeting in Chinese

Enregistrez le fichier. Avant de pouvoir exécuter ce script directement, vous devez le rendre exécutable. Dans le terminal, exécutez la commande chmod :

chmod +x declaration.py

Maintenant, vous pouvez exécuter le script directement sans taper python au préalable :

./declaration.py

Le résultat affichera correctement les deux lignes de texte, y compris les caractères chinois :

Hello, World!
你好, 世界!

La ligne shebang a permis au système de trouver et d'utiliser l'interpréteur Python 3, et la déclaration d'encodage a assuré que les caractères non-ASCII étaient gérés correctement.

Résumé

Dans ce laboratoire, vous avez appris à ajouter des commentaires à votre code Python. Vous vous êtes exercé à utiliser les commentaires sur une seule ligne avec # pour des notes brèves, les commentaires sur plusieurs lignes avec """...""" pour des descriptions plus longues, et les commentaires de déclaration spéciaux comme le shebang et la déclaration d'encodage pour configurer l'exécution du script. En commentant efficacement votre code, vous le rendez plus lisible, maintenable et plus facile à comprendre pour les autres (et pour votre futur vous).