Participer au site avec un Tip
Rechercher
 

Améliorations / Corrections

Vous avez des améliorations (ou des corrections) à proposer pour ce document : je vous remerçie par avance de m'en faire part, cela m'aide à améliorer le site.

Emplacement :

Description des améliorations :

Prologue : commentez vos programmes

Le Zen de Python Variables et types de données


Accès rapide :
Qu'est-ce qu'un commentaire ?
La syntaxe Python pour définir des commentaires.
Les commentaires de documentation (docstring)

Qu'est-ce qu'un commentaire ?

Avant de parler de variables et de type de données, je voulais rapidement commencer à vous parler des commentaires. En programmation, un commentaire est un élément de votre programme qui n'aura aucun effet sur son exécution. Par contre, il aide à comprendre le code de ce programme.

Effectivement, même si vous avez écrit ce programme, il se peut que vous cherchiez à le modifier plusieurs années après. A ce moment-là, vous aurez certainement un peu oublié son fonctionnement : les commentaires vous aideront à le reprendre en main. De même et dans le cadre d'une entreprise, d'autres personnes peuvent être amené à modifier vos codes. Pensez aussi à eux et commentez vos programmes.

La syntaxe Python pour définir des commentaires.

Un commentaire s'introduit via le caractère # et se poursuit jusqu'à la fin de la ligne courante. Reprenons le code de test présenté dans les chapitres précédents : si on y ajoute quelques commentaires, il deviendra peut-être plus clair.

 1 
 2 
 3 
 4 
 5 
 6 
 7 
 8 
 9 
 10 
 11 
 12 
 13 
 14 
 15 
# On demande la saisie de deux valeurs
premiereChaine = input("Veuillez saisir un nombre : ")
secondeChaine = input("Veuillez saisir un autre nombre : ")

# Comme la fonction input renvoi des chaînes de caractères, 
# il est nécessaire de les convertir en valeurs numériques flottantes.
a = float(premiereChaine)
b = float(secondeChaine)

# On utilise ces valeurs pour effectuer quelques calculs
# et on affiche les résultats sur la console via la fonction print.
print("a + b = ", a + b)
print("a - b = ", a - b)
print("a * b = ", a * b)
print("a / b = ", a / b)        # On fait une division.
Un programme Python basique
les lignes 1, 5, 6, 10 et 11 sont des lignes de commentaires.
un commentaire ne commence pas obligatoirement dès le premier caractère de la ligne. Il peut commencer à la suite d'une instruction de code, comme le montre la ligne 15.

Outre la syntaxe que je viens de vous présenter, il faut savoir qu'il existe des conventions de codage en Python : ces règles sont rassemblées dans un document appelé la PEP 8 et un chapitre est dédié aux conventions relatives aux commentaires.

une PEP (Python Enhancement Proposal) est un document spécifiant un aspect ou une évolution du langage de programmation. La PEP 0 liste l'ensemble des PEPs Python.

Ce qu'il faut retenir de cette PEP, c'est qu'il est recommandé qu'un commentaire commence par la séquence #   (un caractère espace est souhaité juste après le caractère #). Du point de vue de l'exécution du code, l'espace n'est pas obligatoire, mais il est recommandé du point de vue du style de codage et de la lisibilité.

Certains IDEs sont capables de vérifier le respect des règles définies dans la PEP 8 : c'est, bien entendu, le cas de PyCharm. La capture d'écran ci-dessous montre l'avertissment affiché si vous ne repectez pas cette convention.

PyCharm vous indique, lors de la saisie d'un commentaire, si la PEP 8 n'y est pas respectée

Les commentaires de documentation (docstring)

Il existe une autre manière de mettre des commentaires dans un code Python : vous pouvez utiliser les docstrings. Ce type de commentaire est utilisé pour générer des documentations sur votre programme. A titre d'exemple, voici un code qui débute par un docstring (entre triple quotes ou triple double-quotes).

 1 
 2 
 3 
 4 
 5 
 6 
 7 
 8 
 9 
 10 
 11 
 12 
 13 
 14 
 15 
 16 
 17 
 18 
 19 
 20 
 21 
"""Ceci est un exemple de code possédant divers commentaires (normaux est docstring).
            
Il est tiré du tutoriel Python disponible à l'adresse suivante :
https://koor.fr/Python/Tutorial/python_introduction.wp
"""

# On demande la saisie de deux valeurs
premiereChaine = input("Veuillez saisir un nombre : ")
secondeChaine = input("Veuillez saisir un autre nombre : ")

# Comme la fonction input renvoi des chaînes de caractères, 
# il est nécessaire de les convertir en valeurs numériques flottantes.
a = float(premiereChaine)
b = float(secondeChaine)

# On utilise ces valeurs pour effectuer quelques calculs
# et on affiche les résultats sur la console via la fonction print.
print("a + b = ", a + b)
print("a - b = ", a - b)
print("a * b = ", a * b)
print("a / b = ", a / b)        # On fait une division.
Un exemple de docstring
un commentaire docstring peut s'étendre sur plusieurs lignes de codes étant données qu'il est possède un marqueur de début et un marqueur de fin.

Pour l'heure, nous ne parlerons plus de ces docstrings. Nous y reviendrons bien plus tard dans ce tutoriel.

Le Zen de Python Variables et types de données