DocString
Une docstring est une chaîne de caractères littérale qui apparaît comme première déclaration dans la définition d’un module, d’une fonction, d’une classe ou d’une méthode.
Une telle chaîne devient l’attribut spécial __doc__ de cet objet.
Quelques règles
Les recommandations en matière de rédaction des docstrings se trouvent résumées dans la PEP 257.
Les points essentiels sont les suivants :
- Utiliser des guillemets triples pour entourer les docstrings :
""" ma docstring """, - La docstring se termine par un point :
., - Elle doit décrire la commande de la fonction (c’est-à-dire ce que fait la fonction),
- Si nous devons ajouter plus d’informations (par exemple, sur les arguments), nous devons laisser une ligne vide entre le résumé de la fonction/classe et une description plus détaillée,
- Les docstrings à plusieurs lignes sont acceptables si elles améliorent la lisibilité,
- Il doit y avoir une description des arguments, de la sortie, des exceptions, etc…
Notez qu’il ne s’agit que de recommandations et non de règles strictes
Il existe d’autres recommandations plus précises, comme par exemple :
Docstrings pour Fonctions
La docstring d’une fonction ou d’une méthode doit résumer son comportement et documenter ses arguments et ses valeurs de retour. Elle doit également énumérer toutes les exceptions qui peuvent être soulevées et d’autres arguments facultatifs.
def add_binary(a, b):
'''
Returns the sum of two decimal numbers in binary digits.
Parameters
----------
a (int): A decimal integer
b (int): Another decimal integer
Returns
-------
binary_sum (str): Binary string of the sum of a and b
'''
binary_sum = bin(a+b)[2:]
return binary_sum
Docstrings pour Classes
Les docstrings des classes doivent résumer leur comportement et énumérer les méthodes publiques et les variables d’instance. Les sous-classes, les constructeurs et les méthodes doivent avoir leurs propres docstrings.
class Person:
"""
A class to represent a person.
...
Attributes
----------
name : str
first name of the person
surname : str
family name of the person
age : int
age of the person
Methods
-------
info(additional=""):
Prints the person's name and age.
"""
def __init__(self, name, surname, age):
"""
Constructs all the necessary attributes for the person object.
Parameters
----------
name : str
first name of the person
surname : str
family name of the person
age : int
age of the person
"""
self.name = name
self.surname = surname
self.age = age
def info(self, additional=""):
"""
Prints the person's name and age.
If the argument 'additional' is passed, then it is appended after the main info.
Parameters
----------
additional : str, optional
More info to be displayed (default is None)
Returns
-------
None
"""
print(f'My name is {self.name} {self.surname}. I am {self.age} years old.' + additional)
