Une docstring décrit un module, une fonction, une classe ou une méthode en langage simple pour aider les autres codeurs à mieux comprendre le sens. Vous devez définir la docstring au début de la définition du module, de la fonction, de la classe ou de la méthode. Ce faisant, la docstring devient le __doc__ attribut spécial de cet objet. Vous pouvez accéder à la docstring de n'importe quel objet Python en appelant son __doc__ attribut.
Vous pouvez trouver un tutoriel complet sur la docstring sur mon article de blog :Qu'est-ce que __ doc __ en Python ?
Jetons un coup d'œil à un exemple minimal de docstring :
s = 'hello world' print(s.__doc__)
La sortie est la docstring multiligne suivante de l'objet de fonction de chaîne :
''' str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'. '''
Mais comment pouvez-vous définir la docstring dans une seule ligne de code Python ?
La docstring peut être soit définie sur plusieurs lignes à l'aide des triples guillemets, soit sur une seule ligne.
Docstring en une ligne
Par convention, vous utilisez des docstrings d'une ligne si la fonction, le module, la classe ou la méthode est suffisamment évidente pour justifier une brève explication, mais rien de plus. Vous pouvez placer la docstring à une ligne entre des guillemets simples, des guillemets doubles ou même des guillemets triples. Cependant, enfermer la docstring à une ligne dans un triple guillemet est la manière la plus Pythonique.
Par exemple, la fonction suivante peut être facilement comprise. Par conséquent, une docstring d'une seule ligne est suffisante pour décrire son comportement :
def add(x, y):
'''Add both arguments and returns their sum.'''
return x + y
print(add.__doc__)
# Add both arguments and returns their sum. Certaines conventions doivent être prises en compte lors de l'écriture de docstrings à une ligne :
- Utilisez des guillemets triples pour la docstring à une ligne, même si cela n'est pas strictement nécessaire. Cela améliore la cohérence et simplifie les extensions ultérieures de la docstring.
- Placez les guillemets fermants sur la même ligne que les guillemets ouvrants pour plus de clarté. Sinon, ce ne serait pas une docstring en une seule ligne.
- N'utilisez pas de ligne vide avant ou après la docstring. Commencez tout de suite à coder !
- Si possible, formulez la docstring sous la forme d'une phrase se terminant par un point. Pourquoi? Parce que cela vous encourage à écrire des docstrings prescriptifs tels que "Do X" ou "Return Y" plutôt que des descriptifs "Returns X" ou "Does Y".
- N'utilisez pas la docstring comme une "signature" réitérant les informations déjà données dans la définition de la fonction/méthode.
Jusqu'ici tout va bien. Mais s'il s'agit d'une docstring d'une seule ligne, à quoi ressemble une docstring multiligne ?
Docstring multi-lignes
Une docstring multi-lignes se compose de plusieurs lignes de code Python :
def add(a=0, b=2):
"""Add two integers.
Keyword arguments:
a – the first argument (default 0)
b – the second argument (default 2)
"""
if a == 0:
return b
else:
return a + b Dans ce cas, la docstring multi-lignes est plus compliquée. Il commence d'abord par une description générale de la fonction, suivie d'une explication sous forme de liste de tous les arguments. C'est une façon propre et lisible d'écrire des docstrings !
Essayez-le vous-même :jetez un œil au shell de code interactif suivant :
Exercice :Imprimez la docstring dans le shell Python et exécutez-la dans votre navigateur !
Meilleures pratiques
Il existe quelques bonnes pratiques appelées Conventions Docstring tel que défini dans la norme officielle PEP. Respectez-les lors de la définition de vos docstrings. Voici les 7 conventions de docstring les plus importantes :
- Tous les modules, fonctions, méthodes et classes doivent avoir des docstrings.
- Utilisez toujours
"""triple double quotes"""autour de vos docstrings pour des raisons de cohérence. - Utilisez des guillemets triples même si la docstring tient sur une seule ligne. Cela permet une expansion facile plus tard.
- Pas de ligne vide avant ou après la docstring, sauf pour les classes où vous devez ajouter une ligne après la docstring.
- Utilisez une phrase qui décrit ce que fait votre code, telle que
"""Do X and return Y."""se terminant par une période. N'utilisez pas de description telle que"""Does X and returns Y.""". - Les docstrings multi-lignes commencent par une ligne de résumé (comme la docstring à une ligne), suivie d'une ligne vide, suivie d'une description plus précise telle que
argument - – name of the person (string)pour décrire l'un des arguments de la fonction ou de la méthode. Par exemple, vous pouvez utiliser une ligne par argument. - Commencer une docstring multi-lignes immédiatement dans la même ligne de l'ouverture
"""triple double strings...plutôt que de commencer le texte dans une nouvelle ligne.
