←
Commentaires

1.7 Commentaires

Objectifs d'apprentissage

À la fin de cette section, vous devriez être capable de :

  • Écrire des commentaires concis et pertinents qui expliquent la fonctionnalité prévue du code.
  • Écrire une docstring (commentaire plus détaillé) qui décrit la fonctionnalité du programme.

Le caractère croisillon

Les commentaires (comments) sont de courtes phrases qui expliquent ce que fait le code. Ex. : Les lignes 1, 8 et 10 du programme suivant contiennent des commentaires. Chaque commentaire commence par un caractère croisillon (#). Tout texte situé entre le caractère croisillon et la fin de la ligne est ignoré lors de l'exécution du programme. En revanche, les caractères croisillon à l'intérieur de chaînes de caractères sont traités comme du texte ordinaire. Ex. : La chaîne "Item #1: " ne contient pas de commentaire.

Lors de l'écriture de commentaires :

  • Le caractère # doit être suivi d'une seule espace. Ex. : # End of menu est plus facile à lire que #End of menu.
  • Les commentaires doivent expliquer le but du code, et non se contenter de répéter le code lui-même. Ex. : # Get the user's preferences est plus descriptif que # Input item1 and item2.

Exemple 1.2

Programme avec trois commentaires

1
# Display the menu options
2
print("Lunch Menu")
3
print("----------")
4
print("Burrito")
5
print("Enchilada")
6
print("Taco")
7
print("Salad")
8
print() # End of menu
9
10
# Get the user's preferences
11
item1 = input("Item #1: ")
12
item2 = input("Item #2: ")

Concepts en pratique

Commentaires simples

1.
Le but principal de l'écriture de commentaires est de _____.
  1. éviter d'écrire des erreurs de syntaxe
  2. expliquer ce que fait le code
  3. rendre le code plus rapide
2.
Quel symbole est utilisé pour les commentaires en Python ?
  1. #
  2. /*
  3. //
3.
Quel commentaire est correctement formaté ?
  1. 0 espace :
    #Get the user input
  2. 1 espace :
    # Get the user input
  3. 2 espaces :
    #  Get the user input

Qualité du code

Le programme d'exemple ci-dessus comportait deux parties : (1) afficher les options du menu, et (2) obtenir les préférences de l'utilisateur. Ensemble, les lignes vides et les commentaires mettent en évidence la structure globale du programme.

Les programmeurs passent plus de temps à lire du code qu'à en écrire. Par conséquent, il est important de rendre le code plus facile à lire et à comprendre pour les autres. Deux façons d'améliorer la qualité du code consistent à :

  • Séparer chaque partie (les lignes ayant un objectif similaire) par une ligne vide.
  • Écrire un commentaire avant chaque partie. Chaque ligne n'a pas besoin d'un commentaire.

Faites le point

Commentaires dans un programme

Accéder au contenu multimédia

Concepts en pratique

Qualité du code

4.
Quel commentaire est le plus utile pour le code suivant ? 
print("You said:", adj1 + " " + noun1)
  1. # Append adj1 and noun1
  2. # Print out a bunch of stuff
  3. # Show the resulting phrase
5.
Où doit-on insérer une ligne vide ?
1
name = input("Whose birthday is today? ")
2
print("Happy birthday to", name)
3
print("Everyone cheer for", name)
  1. Après la ligne 1
  2. Après la ligne 2
  3. Après la ligne 3
6.
Pour empêcher temporairement l'exécution d'une ligne, on peut . . .
  1. introduire une erreur de syntaxe dans la ligne.
  2. supprimer la ligne du programme.
  3. insérer un # au début de la ligne.

Documentation

Les programmes Python peuvent facultativement commencer par une chaîne appelée docstring. Une docstring est une documentation rédigée pour les personnes qui utiliseront le programme sans nécessairement lire le code source. La majeure partie de la documentation officielle sur docs.python.org est générée à partir de docstrings.

La documentation pouvant être longue, les docstrings sont généralement écrites sous la forme de chaînes multilignes ("""). Les éléments courants d'une docstring comprennent un résumé d'une ligne, une ligne vide et une description plus détaillée.

Faites le point

Docstring sur les vacances

Accéder au contenu multimédia

Concepts en pratique

Documentation

7.
Le but principal de l'écriture de docstrings est de . . .
  1. résumer le but ou l'utilisation du programme.
  2. expliquer le fonctionnement de chaque partie du code.
  3. tenir à jour une liste d'idées de nouvelles fonctionnalités.
8.
Laquelle des propositions suivantes n'est PAS une docstring ?
  1. """Vacations Madlib."""
  2. """Vacations Madlib.
This program asks the user for two adjectives
and two nouns, which are then used to print
a funny story about a vacation.
"""
  3. # Vacations Madlib.
#
# This program asks the user for two adjectives
# and two nouns, which are then used to print
# a funny story about a vacation.
9.
Quelle docstring est la plus utile pour ce programme ?
  1. """Vacations Madlib."""
  2. """Vacations Madlib. 

This program asks the user for two adjectives
and two nouns, which are then used to print
a funny story about a vacation.
"""
  3. """Vacations Madlib.

This program asks the user for two adjectives
and two nouns, which are then used to print
a funny story about a vacation. The code uses
four variables to store the user input: two for
the adjectives, and two for the nouns. The
output is displayed on seven lines, beginning
with a blank line after the input.
"""

À vous d'essayer

Qui fête son anniversaire ?

Ajoutez deux commentaires au programme suivant : un pour l'entrée et un pour la sortie. Séparez l'entrée et la sortie par une ligne vide. Ensuite, comparez vos commentaires avec la solution type et posez-vous les questions suivantes :

  • Vos commentaires sont-ils plus longs ou plus courts ? Pourquoi ?
  • Le formatage de vos commentaires est-il correct ?
Accéder au contenu multimédia

À vous d'essayer

Calcul de la gravité

Écrivez une docstring pour le programme suivant. La première ligne de la docstring doit expliquer, en une phrase courte, ce qu'est le programme. La deuxième ligne de la docstring doit être vide. La troisième ligne et les suivantes doivent inclure une explication plus longue de ce que fait le programme. À la fin de la docstring, ajoutez une ligne indiquant "Author: " suivi de votre nom.

Accéder au contenu multimédia