Créer des commentaires Python de la bonne manière

Les commentaires sont des notes que les programmeurs ajoutent à leur code pour expliquer ce que ce code est censé faire. Les compilateurs ou 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 derrière les logiciels.

Bien que les commentaires soient principalement destinés aux développeurs, la rédaction de commentaires 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 dans votre code peuvent fournir du contenu pour votre documentation.

Regardons sous le capot des commentaires en Python.

Commentaires en 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 vaut mieux ne pas avoir de commentaire du tout plutôt 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 gênants et réduire la qualité du code. Les commentaires ne sont pas nécessaires lorsque le but du code est évident.

En Python, une ligne est déclarée comme 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 manières de déclarer des commentaires sur une seule ligne : les commentaires en ligne et les commentaires en bloc.

Commentaires en ligne

Les commentaires en ligne fournissent de brèves descriptions des variables et des opérations simples et sont écrits sur la même ligne que l'instruction de code :

 border = x + 10 # Make offset of 10px

Le commentaire explique la fonction du code dans la même instruction que le code.

Bloquer les commentaires

Les commentaires de bloc sont utilisés pour décrire une logique complexe dans le code. Les commentaires de bloc en Python sont construits de la même manière que les commentaires en ligne - la seule différence est que les commentaires de bloc sont écrits sur une ligne distincte :

 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 commentaires de bloc, 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 poussent souvent les lignes au-delà de 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 en charge nativement les commentaires multilignes, ce qui signifie qu'il n'y a pas de disposition spéciale pour les définir. Malgré cela, des commentaires sur plusieurs lignes sont souvent utilisés.

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

 # interpreter # ignores # these lines

Vous pouvez également utiliser la syntaxe des chaînes multilignes. En Python, vous pouvez définir des chaînes multilignes en les mettant entre """ , triples guillemets doubles ou ''' , triples guillemets simples :

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

Dans le code ci-dessus, la chaîne multiligne n'est pas affectée à une variable, ce qui fait que la chaîne fonctionne comme un commentaire. Au moment de l'exécution, Python ignore la chaîne et elle n'est pas incluse dans le bytecode. L'exécution du code ci-dessus produit le résultat suivant :

 Multi-Line Comment

Commentaires spéciaux

En plus de rendre votre code lisible, les commentaires ont également des objectifs particuliers en Python, tels que la planification de futurs ajouts de code et la génération de documentation.

Commentaires Python Docstring

En Python, les docstrings sont des commentaires multilignes 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 haute 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 de 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 a fourni 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 l'utilisation de cette méthode.

Une docstring définie juste en dessous de la signature de la fonction ou de la classe peut également être renvoyée à l'aide de 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 en 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 à l'aide de l'indicateur -i , vous pouvez voir comment cette docstring sera analysée par Python. Exécutez le code ci-dessus en tapant python -i file.py .

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' get_person.__ doc__ peut également être utilisé pour récupérer et modifier les docstrings par programmation. Après avoir ajouté "Some more new information" dans l'exemple ci-dessus, il apparaît dans le deuxième appel à help(get_person) . Pourtant, il est peu probable que vous ayez besoin de modifier dynamiquement les docstrings au moment de l'exécution comme celui-ci.

À FAIRE Commentaires

Lors de l'écriture de code, il y a des occasions où vous voudrez 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 utiles lorsque vous planifiez des mises à jour ou des modifications de votre code, ou si vous souhaitez informer les utilisateurs ou 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 pseudocode - ils doivent simplement expliquer brièvement la fonction du code non encore écrit.

Les commentaires TODO et les commentaires de bloc sur une seule ligne sont très similaires, et la seule différence 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 en évidence ces commentaires pour le programmeur, l'interpréteur Python ne voit pas les commentaires TODO différemment des commentaires de bloc.

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 garantir la fiabilité et la qualité. Vous trouverez ci-dessous quelques conseils pour rédiger des commentaires de haute qualité en Python.

Évitez l'évident

Les commentaires qui énoncent des évidences n'ajoutent aucune valeur à votre code et doivent être évités. Par example:

 x = x + 4 # increase x by 4

Ce commentaire n'est pas utile, car il indique simplement ce que fait le code 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 plus utilement, l'exemple ci-dessus pourrait ressembler à ceci :

 x = x + 4 # increase the border width

Gardez les commentaires Python courts et doux

Gardez vos commentaires courts et faciles à comprendre. Ils doivent être écrits en prose standard, et non en pseudo-code, et doivent remplacer le besoin 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 d'un programmeur. Par example:

 # 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 doivent fournir un résumé général du code. Ce commentaire peut être réécrit comme suit :

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

Utilisez les identifiants avec précaution

Les identifiants doivent être utilisés avec précaution dans les commentaires. La modification des noms ou des cas d'identifiant peut semer la confusion chez le lecteur. Exemple:

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

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

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

SEC et HUMIDE

Lorsque vous écrivez du code, vous voulez adhérer au principe DRY (ne vous répétez pas) et éviter WET (tout écrire deux fois).

C'est également vrai pour les commentaires. Évitez d'utiliser plusieurs instructions 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 d'être prudent lorsque vous fusionnez des commentaires : la fusion négligente de plusieurs commentaires peut entraîner un énorme commentaire qui viole les guides de style et est difficile à suivre pour le lecteur.

Rappelez-vous 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 mis en retrait au même niveau que le code qu'ils décrivent. Lorsqu'ils ne le sont pas, ils peuvent être difficiles à suivre.

Par exemple, ce commentaire n'est pas mis en retrait ou positionné correctement :

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

Il peut être réécrit comme suit :

 # 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 de code compréhensible. L'investissement que vous faites en écrivant un commentaire est un investissement que votre futur moi - ou d'autres développeurs qui ont besoin de travailler sur votre base de code - apprécieront. Les commentaires vous permettent également d'obtenir des informations plus approfondies sur votre code.

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

Écrire de bons commentaires est une compétence qui doit être étudiée et développée. Pour vous entraîner à écrire des commentaires, envisagez de revenir en arrière et d'ajouter des commentaires à certains de vos projets précédents. Pour vous inspirer et voir les meilleures pratiques en action, consultez des 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 transférer votre code de GitHub vers le cloud en quelques secondes.