Bien que les commentaires soient principalement destin\u00e9s aux d\u00e9veloppeurs<\/a>, en r\u00e9diger d’efficaces peut \u00e9galement aider \u00e0 produire une excellente documentation pour les utilisateurs de votre code. Avec l’aide de g\u00e9n\u00e9rateurs de documents comme Sphinx<\/a> pour les projets Python, les commentaires de votre code peuvent fournir du contenu pour votre documentation.<\/p>\n Regardons sous le capot des commentaires dans Python.<\/p>\n Selon le guide de style Python PEP 8<\/a>, il y a plusieurs choses \u00e0 garder \u00e0 l’esprit lors de la r\u00e9daction de commentaires :<\/p>\n En Python, une ligne est d\u00e9clar\u00e9e comme un commentaire lorsqu’elle commence par le symbole Les commentaires en ligne fournissent de courtes descriptions des variables et des op\u00e9rations simples et sont \u00e9crits sur la m\u00eame ligne que l’\u00e9nonc\u00e9 du code :<\/p>\n Le commentaire explique la fonction du code dans la m\u00eame d\u00e9claration que le code.<\/p>\n Les blocs de commentaires sont utilis\u00e9s pour d\u00e9crire une logique complexe dans le code. Les blocs de commentaires dans Python sont construits de mani\u00e8re similaire aux commentaires en ligne – la seule diff\u00e9rence est que les blocs de commentaires sont \u00e9crits sur une ligne s\u00e9par\u00e9e :<\/p>\n Notez que lorsque vous utilisez des blocs de commentaires, les commentaires sont \u00e9crits 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\u00e8res, et les commentaires en ligne font souvent d\u00e9passer cette longueur. C’est pourquoi les blocs de commentaires sont \u00e9crits pour d\u00e9crire le code sur des lignes s\u00e9par\u00e9es.<\/p>\n Python ne prend pas nativement en charge les commentaires multi-lignes, ce qui signifie qu’il n’existe aucune disposition sp\u00e9ciale pour les d\u00e9finir. Malgr\u00e9 cela, les commentaires s’\u00e9tendant sur plusieurs lignes sont souvent utilis\u00e9s.<\/p>\n Vous pouvez cr\u00e9er un commentaire multi-lignes \u00e0 partir de plusieurs commentaires d’une seule ligne en faisant pr\u00e9c\u00e9der chaque ligne de Vous pouvez \u00e9galement utiliser la syntaxe des chaines de caract\u00e8res multi-lignes. En Python, vous pouvez d\u00e9finir des chaines de caract\u00e8res multi-lignes en les entourant de Dans le code ci-dessus, la chaine multi-lignes n’est pas affect\u00e9e \u00e0 une variable, ce qui fait que la chaine fonctionne comme un commentaire. Au moment de l’ex\u00e9cution, Python ignore la chaine, et elle n’est pas incluse dans le bytecode. L’ex\u00e9cution du code ci-dessus produit la sortie suivante :<\/p>\n En plus de rendre votre code lisible, les commentaires servent \u00e9galement \u00e0 des fins particuli\u00e8res en Python, comme la planification de futurs ajouts au code et la g\u00e9n\u00e9ration de documentation.<\/p>\n En Python, les docstrings sont des commentaires de plusieurs lignes qui expliquent comment utiliser une fonction ou une classe donn\u00e9e. La documentation de votre code est am\u00e9lior\u00e9e par la cr\u00e9ation de docstrings de qualit\u00e9. Lorsque vous travaillez avec une fonction ou une classe et que vous utilisez la fonction int\u00e9gr\u00e9e Python PEP 257<\/a> fournit une m\u00e9thode standard de d\u00e9claration des docstrings en Python, illustr\u00e9e ci-dessous :<\/p>\n Dans le code ci-dessus, la docstring fournit des d\u00e9tails sur le fonctionnement de la fonction associ\u00e9e. Avec des g\u00e9n\u00e9rateurs de documentation comme Sphinx, cette docstring peut \u00eatre utilis\u00e9e pour donner aux utilisateurs de votre projet un aper\u00e7u de la mani\u00e8re d’utiliser cette m\u00e9thode.<\/p>\n Une docstring d\u00e9finie juste en dessous de la signature de la fonction ou de la classe peut \u00e9galement \u00eatre retourn\u00e9e en utilisant la fonction int\u00e9gr\u00e9e L’appel de fonction L’attribut Lorsque vous \u00e9crivez du code, il arrive que vous souhaitiez mettre en \u00e9vidence certaines lignes ou des blocs entiers \u00e0 am\u00e9liorer. Ces t\u00e2ches sont signal\u00e9es par des commentaires TODO. Les commentaires TODO sont pratiques lorsque vous planifiez des mises \u00e0 jour ou des modifications de votre code, ou si vous souhaitez informer les utilisateurs ou les collaborateurs du projet que des sections sp\u00e9cifiques du code du fichier restent \u00e0 \u00e9crire.<\/p>\n Les commentaires TODO ne doivent pas \u00eatre \u00e9crits sous forme de pseudo-code – ils doivent juste expliquer bri\u00e8vement la fonction du code non encore \u00e9crit.<\/p>\n Les commentaires TODO et les blocs de commentaires\u00e0 une ligne sont tr\u00e8s similaires, et la seule distinction entre eux est que les commentaires TODO doivent commencer par un pr\u00e9fixe TODO :<\/p>\n Il est important de noter que, bien que de nombreux IDE puissent mettre ces commentaires en \u00e9vidence pour le programmeur, l’interpr\u00e9teur Python ne consid\u00e8re pas les commentaires TODO diff\u00e9remment des blocs de commentaires.<\/p>\n Il existe un certain nombre de bonnes pratiques \u00e0 suivre lors de la r\u00e9daction de commentaires pour en assurer la fiabilit\u00e9 et la qualit\u00e9. Vous trouverez ci-dessous quelques conseils pour r\u00e9diger des commentaires de qualit\u00e9 en Python.<\/p>\n Les commentaires qui \u00e9noncent des \u00e9vidences n’apportent aucune valeur ajout\u00e9e \u00e0 votre code et doivent \u00eatre \u00e9vit\u00e9s. Par exemple :<\/p>\n Ce commentaire n’est pas utile, car il indique simplement ce que le code fait sans expliquer pourquoi il doit \u00eatre fait. Les commentaires doivent expliquer le\u00a0 pourquoi \u00bb plut\u00f4t que le \u00ab quoi \u00bb du code qu’ils d\u00e9crivent.<\/p>\n R\u00e9\u00e9crit de mani\u00e8re plus utile, l’exemple ci-dessus pourrait ressembler \u00e0 ceci :<\/p>\n Gardez vos commentaires courts et faciles \u00e0 comprendre. Ils doivent \u00eatre \u00e9crits en prose standard, et non en pseudo-code, et doivent remplacer la n\u00e9cessit\u00e9 de lire le code r\u00e9el pour avoir un aper\u00e7u g\u00e9n\u00e9ral de ce qu’il fait. Trop de d\u00e9tails ou des commentaires complexes ne facilitent pas le travail du programmeur. Par exemple :<\/p>\n Le commentaire ci-dessus fournit plus d’informations que n\u00e9cessaire pour le lecteur. Au lieu de sp\u00e9cifier la logique de base, les commentaires devraient fournir un r\u00e9sum\u00e9 g\u00e9n\u00e9ral du code. Ce commentaire peut \u00eatre r\u00e9\u00e9crit comme ci-dessous :<\/p>\n Les identificateurs doivent \u00eatre utilis\u00e9s avec pr\u00e9caution dans les commentaires. Le changement de noms ou de cas d’identificateurs peut d\u00e9sorienter le lecteur. Exemple :<\/p>\n Le commentaire ci-dessus mentionne Lorsque vous \u00e9crivez du code, vous voulez adh\u00e9rer au principe DRY (Don’t Repeat Yourself) et \u00e9viter le WET (Write Everything Twxice).<\/p>\n Ceci est \u00e9galement vrai pour les commentaires. \u00c9vitez d’utiliser plusieurs d\u00e9clarations pour d\u00e9crire votre code, et essayez de fusionner les commentaires qui expliquent le m\u00eame code en un seul commentaire. Cependant, il est important de faire attention lorsque vous fusionnez des commentaires : la fusion n\u00e9gligente de plusieurs commentaires peut donner lieu \u00e0 un \u00e9norme commentaire qui viole les guides de style et est difficile \u00e0 suivre pour le lecteur.<\/p>\n N’oubliez pas que les commentaires doivent r\u00e9duire le temps de lecture du code.<\/p>\n Dans le code ci-dessus, les commentaires sont inutilement fragment\u00e9s, et peuvent \u00eatre fusionn\u00e9s en un seul commentaire :<\/p>\n Assurez-vous que les commentaires sont indent\u00e9s au m\u00eame niveau que le code qu’ils d\u00e9crivent. S’ils ne le sont pas, ils peuvent \u00eatre difficiles \u00e0 suivre.<\/p>\n Par exemple, ce commentaire n’est pas indent\u00e9 ou positionn\u00e9 correctement :<\/p>\n It can be rewritten as follows:<\/p>\n Les commentaires sont un \u00e9l\u00e9ment important de l’\u00e9criture d’un code compr\u00e9hensible. L’investissement que vous faites en r\u00e9digeant un commentaire est un investissement que votre futur moi – ou d’autres d\u00e9veloppeurs qui doivent travailler sur votre base de code – appr\u00e9ciera. Les commentaires vous permettent \u00e9galement d’obtenir des informations plus approfondies sur votre code.<\/p>\n Dans ce tutoriel, vous en avez appris davantage sur les commentaires en Python, y compris les diff\u00e9rents types de commentaires Python, quand utiliser chacun d’entre eux, et les meilleures pratiques \u00e0 suivre lors de leur cr\u00e9ation.<\/p>\n L’\u00e9criture de bons commentaires est une comp\u00e9tence qui doit \u00eatre \u00e9tudi\u00e9e et d\u00e9velopp\u00e9e. Pour vous entrainer \u00e0 \u00e9crire des commentaires, pensez \u00e0 revenir en arri\u00e8re et \u00e0 ajouter des commentaires \u00e0 certains de vos projets pr\u00e9c\u00e9dents. Pour vous inspirer et voir les meilleures pratiques en action, consultez les projets Python bien document\u00e9s sur GitHub.<\/p>\n Lorsque vous \u00eates pr\u00eat \u00e0 mettre en ligne vos propres projets Python, la plateforme d’h\u00e9bergement d’applications<\/a> de Kinsta peut faire passer votre code de GitHub au cloud<\/a> en quelques secondes.<\/p>\n","protected":false},"excerpt":{"rendered":" Les commentaires sont des notes que les programmeurs ajoutent \u00e0 leur code pour expliquer ce que ce code est cens\u00e9 faire. Les compilateurs ou les interpr\u00e8teurs …<\/p>\n","protected":false},"author":275,"featured_media":65186,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_kinsta_gated_content":false,"_kinsta_gated_content_redirect":"","footnotes":""},"tags":[],"topic":[1003],"class_list":["post-65185","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","topic-python"],"yoast_head":"\nLes commentaires dans Python<\/h2>\n
\n
#<\/code>. Lorsque l’interpr\u00e9teur Python rencontre #<\/code> dans votre code, il ignore tout ce qui suit ce symbole et ne produit aucune erreur. Il existe deux fa\u00e7ons de d\u00e9clarer des commentaires d’une seule ligne : les commentaires en ligne et les blocs commentaires.<\/p>\nCommentaires en ligne<\/h3>\n
border = x + 10 # Make offset of 10px<\/code><\/pre>\nBloc de commentaires<\/h3>\n
import csv\nfrom itertools import groupby\n\n# Get a list of names in a sequence from the csv file\nwith open('new-top-firstNames.csv') as f:\n file_csv = csv.reader(f)\n\n# Skip the header part: (sr, name, perc)\nheader = next(file_csv)\n \n# Only name from (number, name, perc)\npersons = [ x[1] for x in file_csv]\n\n# Sort the list by first letter because \n# The groupby function looks for sequential data.\npersons.sort(key=lambda x:x[0])\ndata = groupby(persons, key=lambda x:x[0])\n\n# Get every name as a list \ndata_grouped = {}\nfor k, v in data:\n # Get data in the form \n # {'A' : [\"Anthony\", \"Alex\"], \"B\" : [\"Benjamin\"]}\n data_grouped[k] = list(v)<\/code><\/pre>\nCommentaires multi-lignes<\/h3>\n
#<\/code>:<\/p>\n# interpreter \n# ignores\n# these lines<\/code><\/pre>\n\"\"\"<\/code>, de guillemets doubles triples, ou de '''<\/code>, de guillemets simples triples :<\/p>\nprint(\"Multi-Line Comment\")\n\"\"\"\nThis\nString is \nMulti line \n\"\"\"<\/code><\/pre>\nMulti-Line Comment<\/code><\/pre>\n\nCommentaires sp\u00e9ciaux<\/h2>\n
Commentaires docstring Python<\/h3>\n
help(obj)<\/code>, les docstrings peuvent \u00eatre utiles pour donner un aper\u00e7u de l’objet.<\/p>\nfrom collections import namedtuple\nPerson = namedtuple('Person', ['name', 'age'])\n\n def get_person(name, age, d=False):\n \"\"\"\nReturns a namedtuple(\"name\", \"age\") object.\nAlso returns dict('name', 'age') if arg `d` is True\n\nArguments:\nname \u2013 first name, must be string\nage \u2013 age of person, must be int\nd \u2013 to return Person as `dict` (default=False)\n\n\"\"\"\np = Person(name, age)\nif d:\n return p._asdict()\nreturn p<\/code><\/pre>\nhelp()<\/code>. La fonction help()<\/code> 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)<\/code> peut \u00eatre appel\u00e9 pour r\u00e9v\u00e9ler les docstrings associ\u00e9s \u00e0 la fonction get_person<\/code>. Si vous ex\u00e9cutez le code ci-dessus dans un shell interactif en utilisant le signalement -i<\/code>, vous pouvez voir comment cette docstring sera analys\u00e9e par Python. Ex\u00e9cutez le code ci-dessus en tapant python -i file.py<\/code>.<\/p>\n![\"Commentaires](\"https:\/\/kinsta.com\/wp-content\/uploads\/2022\/12\/parsing-python-docstrings-on-command-line.png\")
help(get_person)<\/code> renvoie une docstring pour votre fonction. La sortie contient get_person(name, age, d=False)<\/code>, qui est une signature de fonction que Python ajoute automatiquement.<\/p>\nget_person.__ doc__<\/code> peut \u00e9galement \u00eatre utilis\u00e9 pour r\u00e9cup\u00e9rer et modifier les docstrings de mani\u00e8re programmatique. Apr\u00e8s l’ajout de \u00ab Some more new information \u00bb dans l’exemple ci-dessus, il apparait dans le deuxi\u00e8me appel \u00e0 help(get_person)<\/code>. Cependant, il est peu probable que vous ayez besoin de modifier dynamiquement les docstrings au moment de l’ex\u00e9cution comme ceci.<\/p>\nCommentaires TODO<\/h3>\n
# TODO Get serialized data from the CSV file\n# TODO Perform calculations on the data\n# TODO Return to the user<\/code><\/pre>\nMeilleures pratiques lors de la r\u00e9daction de commentaires Python<\/h2>\n
\u00c9vitez les \u00e9vidences<\/h3>\n
x = x + 4 # increase x by 4<\/code><\/pre>\nx = x + 4 # increase the border width<\/code><\/pre>\nGardez les commentaires Python courts et agr\u00e9ables<\/h3>\n
# return area by performing, Area of cylinder = (2*PI*r*h) + (2*PI*r*r)\ndef get_area(r,h):\n return (2*3.14*r*h) + (2*3.14*r*r)<\/code><\/pre>\n# return area of cylinder\ndef get_area(r,h):\n return (2*3.14*r*h) + (2*3.14*r*r)<\/code><\/pre>\nUtilisez les identificateurs avec pr\u00e9caution<\/h3>\n
# return class() after modifying argument\ndef func(cls, arg):\n return cls(arg+5)\n<\/code><\/pre>\nclass<\/code> et argument<\/code>, qui ne se trouvent pas dans le code. Ce commentaire peut \u00eatre r\u00e9\u00e9crit comme suit :<\/p>\n# return cls() after modifying arg\ndef func(cls, arg):\n return cls(arg+5)<\/code><\/pre>\nDRY et WET<\/h3>\n
# function to do x work\ndef do_something(y):\n # x work cannot be done if y is greater than max_limit\n if y < 400:\n print('doing x work')<\/code><\/pre>\n# function to do x if arg:y is less than max_limit\ndef do_something(y):\n if y in range(400):\n print('doing x work')<\/code><\/pre>\nIndentation coh\u00e9rente<\/h3>\n
for i in range(2,20, 2):\n# only even numbers\n if verify(i):\n# i should be verified by verify()\n perform(x)<\/code><\/pre>\n# only even numbers\nfor i in range(2,20, 2):\n # i should be verified by verify()\n if verify(i):\n perform(x)<\/code><\/pre>\n\nR\u00e9sum\u00e9<\/h2>\n