Les commentaires sont des notes que les programmeurs ajoutent à leur code pour expliquer ce que ce code est censé faire. Les compilateurs ou les interprèteurs qui transforment le code en action ignorent les commentaires, mais ils peuvent être essentiels à la gestion des projets logiciels.

Les commentaires aident à expliquer votre code Python aux autres programmeurs et peuvent vous rappeler pourquoi vous avez fait les choix que vous avez faits. Les commentaires facilitent le débogage et la révision du code en aidant les futurs programmeurs à comprendre les choix de conception des logiciels.

Bien que les commentaires soient principalement destinés aux développeurs, en rédiger d’efficaces peut également aider à produire une excellente documentation pour les utilisateurs de votre code. Avec l’aide de générateurs de documents comme Sphinx pour les projets Python, les commentaires de votre code peuvent fournir du contenu pour votre documentation.

Regardons sous le capot des commentaires dans Python.

Les commentaires dans Python

Selon le guide de style Python PEP 8, il y a plusieurs choses à garder à l’esprit lors de la rédaction de commentaires :

  • Les commentaires doivent toujours être des phrases complètes et concises.
  • Il est préférable de ne pas avoir de commentaire du tout qu’un commentaire difficile à comprendre ou inexact.
  • Les commentaires doivent être mis à jour régulièrement pour refléter les modifications apportées à votre code.
  • Trop de commentaires peuvent être distrayants et réduire la qualité du code. Les commentaires ne sont pas nécessaires lorsque l’objectif du code est évident.

En Python, une ligne est déclarée comme un commentaire lorsqu’elle commence par le symbole #. Lorsque l’interpréteur Python rencontre # dans votre code, il ignore tout ce qui suit ce symbole et ne produit aucune erreur. Il existe deux façons de déclarer des commentaires d’une seule ligne : les commentaires en ligne et les blocs commentaires.

Commentaires en ligne

Les commentaires en ligne fournissent de courtes descriptions des variables et des opérations simples et sont écrits sur la même ligne que l’énoncé du code :

border = x + 10  # Make offset of 10px

Le commentaire explique la fonction du code dans la même déclaration que le code.

Bloc de commentaires

Les blocs de commentaires sont utilisés pour décrire une logique complexe dans le code. Les blocs de commentaires dans Python sont construits de manière similaire aux commentaires en ligne – la seule différence est que les blocs de commentaires sont écrits sur une ligne séparée :

import csv
from itertools import groupby

# Get a list of names in a sequence from the csv file
with open('new-top-firstNames.csv') as f:
    file_csv = csv.reader(f)

# Skip the header part: (sr, name, perc)
header = next(file_csv)
    
# Only name from (number, name, perc)
persons = [ x[1] for x in file_csv]

# Sort the list by first letter because 
# The groupby function looks for sequential data.
persons.sort(key=lambda x:x[0])
data = groupby(persons, key=lambda x:x[0])

# Get every name as a list 
data_grouped = {}
for k, v in data:
    # Get data in the form 
    # {'A' : ["Anthony", "Alex"], "B" : ["Benjamin"]}
    data_grouped[k] = list(v)

Notez que lorsque vous utilisez des blocs de commentaires, les commentaires sont écrits au-dessus du code qu’ils expliquent. Le guide de style Python PEP8 stipule qu’une ligne de code ne doit pas contenir plus de soixante-dix-neuf caractères, et les commentaires en ligne font souvent dépasser cette longueur. C’est pourquoi les blocs de commentaires sont écrits pour décrire le code sur des lignes séparées.

Commentaires multi-lignes

Python ne prend pas nativement en charge les commentaires multi-lignes, ce qui signifie qu’il n’existe aucune disposition spéciale pour les définir. Malgré cela, les commentaires s’étendant sur plusieurs lignes sont souvent utilisés.

Vous pouvez créer un commentaire multi-lignes à partir de plusieurs commentaires d’une seule ligne en faisant précéder chaque ligne de #:

# interpreter 
# ignores
# these lines

Vous pouvez également utiliser la syntaxe des chaines de caractères multi-lignes. En Python, vous pouvez définir des chaines de caractères multi-lignes en les entourant de """, de guillemets doubles triples, ou de ''', de guillemets simples triples :

print("Multi-Line Comment")
"""
This
String is 
Multi line 
"""

Dans le code ci-dessus, la chaine multi-lignes n’est pas affectée à une variable, ce qui fait que la chaine fonctionne comme un commentaire. Au moment de l’exécution, Python ignore la chaine, et elle n’est pas incluse dans le bytecode. L’exécution du code ci-dessus produit la sortie suivante :

Multi-Line Comment

Commentaires spéciaux

En plus de rendre votre code lisible, les commentaires servent également à des fins particulières en Python, comme la planification de futurs ajouts au code et la génération de documentation.

Commentaires docstring Python

En Python, les docstrings sont des commentaires de plusieurs lignes qui expliquent comment utiliser une fonction ou une classe donnée. La documentation de votre code est améliorée par la création de docstrings de qualité. Lorsque vous travaillez avec une fonction ou une classe et que vous utilisez la fonction intégrée help(obj), les docstrings peuvent être utiles pour donner un aperçu de l’objet.

Python PEP 257 fournit une méthode standard de déclaration des docstrings en Python, illustrée ci-dessous :

from collections import namedtuple
Person = namedtuple('Person', ['name', 'age'])

 def get_person(name, age, d=False):
    """
Returns a namedtuple("name", "age") object.
Also returns dict('name', 'age') if arg `d` is True

Arguments:
name  – first name, must be string
age   – age of person, must be int
d     – to return Person as `dict` (default=False)

"""
p = Person(name, age)
if d:
    return p._asdict()
return p

Dans le code ci-dessus, la docstring fournit des détails sur le fonctionnement de la fonction associée. Avec des générateurs de documentation comme Sphinx, cette docstring peut être utilisée pour donner aux utilisateurs de votre projet un aperçu de la manière d’utiliser cette méthode.

Une docstring définie juste en dessous de la signature de la fonction ou de la classe peut également être retournée en utilisant la fonction intégrée help(). La fonction help() prend un nom d’objet ou de fonction comme argument, et renvoie les docstrings de la fonction comme sortie. Dans l’exemple ci-dessus, help(get_person) peut être appelé pour révéler les docstrings associés à la fonction get_person. Si vous exécutez le code ci-dessus dans un shell interactif en utilisant le signalement -i, vous pouvez voir comment cette docstring sera analysée par Python. Exécutez le code ci-dessus en tapant python -i file.py.

Commentaires de la docstring Python analysés dans l'interface de ligne de commande.
Commentaires de la docstring Python analysés dans l’interface de ligne de commande.

L’appel de fonction help(get_person) renvoie une docstring pour votre fonction. La sortie contient get_person(name, age, d=False), qui est une signature de fonction que Python ajoute automatiquement.

L’attribut get_person.__ doc__ peut également être utilisé pour récupérer et modifier les docstrings de manière programmatique. Après l’ajout de « Some more new information » dans l’exemple ci-dessus, il apparait dans le deuxième appel à help(get_person). Cependant, il est peu probable que vous ayez besoin de modifier dynamiquement les docstrings au moment de l’exécution comme ceci.

Commentaires TODO

Lorsque vous écrivez du code, il arrive que vous souhaitiez mettre en évidence certaines lignes ou des blocs entiers à améliorer. Ces tâches sont signalées par des commentaires TODO. Les commentaires TODO sont pratiques lorsque vous planifiez des mises à jour ou des modifications de votre code, ou si vous souhaitez informer les utilisateurs ou les collaborateurs du projet que des sections spécifiques du code du fichier restent à écrire.

Les commentaires TODO ne doivent pas être écrits sous forme de pseudo-code – ils doivent juste expliquer brièvement la fonction du code non encore écrit.

Les commentaires TODO et les blocs de commentairesà une ligne sont très similaires, et la seule distinction entre eux est que les commentaires TODO doivent commencer par un préfixe TODO :

# TODO Get serialized data from the CSV file
# TODO Perform calculations on the data
# TODO Return to the user

Il est important de noter que, bien que de nombreux IDE puissent mettre ces commentaires en évidence pour le programmeur, l’interpréteur Python ne considère pas les commentaires TODO différemment des blocs de commentaires.

Meilleures pratiques lors de la rédaction de commentaires Python

Il existe un certain nombre de bonnes pratiques à suivre lors de la rédaction de commentaires pour en assurer la fiabilité et la qualité. Vous trouverez ci-dessous quelques conseils pour rédiger des commentaires de qualité en Python.

Évitez les évidences

Les commentaires qui énoncent des évidences n’apportent aucune valeur ajoutée à votre code et doivent être évités. Par exemple :

x = x + 4 # increase x by 4

Ce commentaire n’est pas utile, car il indique simplement ce que le code fait sans expliquer pourquoi il doit être fait. Les commentaires doivent expliquer le  pourquoi » plutôt que le « quoi » du code qu’ils décrivent.

Réécrit de manière plus utile, l’exemple ci-dessus pourrait ressembler à ceci :

x = x + 4 # increase the border width

Gardez les commentaires Python courts et agréables

Gardez vos commentaires courts et faciles à comprendre. Ils doivent être écrits en prose standard, et non en pseudo-code, et doivent remplacer la nécessité de lire le code réel pour avoir un aperçu général de ce qu’il fait. Trop de détails ou des commentaires complexes ne facilitent pas le travail du programmeur. Par exemple :

# return area by performing, Area of cylinder = (2*PI*r*h) + (2*PI*r*r)
def get_area(r,h):
    return (2*3.14*r*h) + (2*3.14*r*r)

Le commentaire ci-dessus fournit plus d’informations que nécessaire pour le lecteur. Au lieu de spécifier la logique de base, les commentaires devraient fournir un résumé général du code. Ce commentaire peut être réécrit comme ci-dessous :

# return area of cylinder
def get_area(r,h):
    return (2*3.14*r*h) + (2*3.14*r*r)

Utilisez les identificateurs avec précaution

Les identificateurs doivent être utilisés avec précaution dans les commentaires. Le changement de noms ou de cas d’identificateurs peut désorienter le lecteur. Exemple :

# return class() after modifying argument
def func(cls, arg):
    return cls(arg+5)

Le commentaire ci-dessus mentionne class et argument, qui ne se trouvent pas dans le code. Ce commentaire peut être réécrit comme suit :

# return cls() after modifying arg
def func(cls, arg):
    return cls(arg+5)

DRY et WET

Lorsque vous écrivez du code, vous voulez adhérer au principe DRY (Don’t Repeat Yourself) et éviter le WET (Write Everything Twxice).

Ceci est également vrai pour les commentaires. Évitez d’utiliser plusieurs déclarations pour décrire votre code, et essayez de fusionner les commentaires qui expliquent le même code en un seul commentaire. Cependant, il est important de faire attention lorsque vous fusionnez des commentaires : la fusion négligente de plusieurs commentaires peut donner lieu à un énorme commentaire qui viole les guides de style et est difficile à suivre pour le lecteur.

N’oubliez pas que les commentaires doivent réduire le temps de lecture du code.

# function to do x work
def do_something(y):
    # x work cannot be done if y is greater than max_limit
    if y < 400:
      print('doing x work')

Dans le code ci-dessus, les commentaires sont inutilement fragmentés, et peuvent être fusionnés en un seul commentaire :

# function to do x if arg:y is less than max_limit
def  do_something(y):
    if y in range(400):
        print('doing x work')

Indentation cohérente

Assurez-vous que les commentaires sont indentés au même niveau que le code qu’ils décrivent. S’ils ne le sont pas, ils peuvent être difficiles à suivre.

Par exemple, ce commentaire n’est pas indenté ou positionné correctement :

for i in range(2,20, 2):
# only even numbers
    if verify(i):
# i should be verified by verify()
        perform(x)

It can be rewritten as follows:

# only even numbers
for i in range(2,20, 2):
    # i should be verified by verify()
    if verify(i):
        perform(x)

Résumé

Les commentaires sont un élément important de l’écriture d’un code compréhensible. L’investissement que vous faites en rédigeant un commentaire est un investissement que votre futur moi – ou d’autres développeurs qui doivent travailler sur votre base de code – appréciera. Les commentaires vous permettent également d’obtenir des informations plus approfondies sur votre code.

Dans ce tutoriel, vous en avez appris davantage sur les commentaires en Python, y compris les différents types de commentaires Python, quand utiliser chacun d’entre eux, et les meilleures pratiques à suivre lors de leur création.

L’écriture de bons commentaires est une compétence qui doit être étudiée et développée. Pour vous entrainer à écrire des commentaires, pensez à revenir en arrière et à ajouter des commentaires à certains de vos projets précédents. Pour vous inspirer et voir les meilleures pratiques en action, consultez les projets Python bien documentés sur GitHub.

Lorsque vous êtes prêt à mettre en ligne vos propres projets Python, la plateforme d’hébergement d’applications de Kinsta peut faire passer votre code de GitHub au cloud en quelques secondes.

Vivek Singh

Vivek est un développeur Python et Django toujours prêt à apprendre et à enseigner de nouvelles choses à ses collègues développeurs.