Sans une documentation appropriée, il peut être difficile de comprendre, de maintenir et de déboguer votre code. En Python, vous pouvez utiliser les docstrings pour fournir des descriptions concises et des exemples du fonctionnement du code.
Que sont les docstrings ?
Les Docstrings sont des chaînes que vous pouvez ajouter à votre code Python pour expliquer ce qu’il fait et comment l’utiliser. Le morceau de code peut être une fonction Python, un module ou une classe.
Les docstrings ressemblent beaucoup aux commentaires Python standard, mais ils présentent quelques différences. Les commentaires Python fournissent des informations supplémentaires aux développeurs sur le fonctionnement interne du code, telles que des détails d’implémentation ou des mises en garde à garder à l’esprit lors de l’extension du code.
D’autre part, les docstrings fournissent principalement des informations aux utilisateurs du code qui n’ont pas nécessairement besoin de connaître les détails de son implémentation, mais qui ont besoin de comprendre ce qu’il fait et comment l’utiliser.
Vous incluez généralement les docstrings au début du bloc de code que vous souhaitez documenter. Vous devez les placer entre trois guillemets (« » »). Vous pouvez écrire des docstrings d’une ligne ou des docstrings de plusieurs lignes.
Les docstrings d’une ligne conviennent au code simple qui ne nécessite pas beaucoup de documentation.
Voici un exemple d’une fonction appelée multiply. La docstring explique que la fonction multiply prend deux nombres, les multiplie et renvoie le résultat.
def multiply(a, b):
"""Multiplies two numbers and returns the result"""
return a * b
Utilisez des chaînes de documentation sur plusieurs lignes pour les codes plus complexes qui nécessitent une documentation détaillée.
Considérons la classe Car suivante :
class Car:
"""
A class representing a car object. Attributes:
mileage (float): The current mileage of the car.
Methods:
drive(miles): Drives the car for the specified number of miles.
"""
def __init__(self, mileage):
self.mileage = mileage
def drive(self, miles):
"""
Drives the car for the specified number of miles.
Args:
miles (float): The number of miles to drive.
Returns:
None
"""
self.mileage += miles
La docstring de la classe ci-dessus décrit ce qu’elle représente, ses attributs et ses méthodes. Parallèlement, la docstring de la méthode drive fournit des informations sur ce que fait la méthode, les arguments qu’elle attend et ce qu’elle renvoie.
Il est ainsi plus facile pour toute personne travaillant avec cette…
Lire la suite de l’article sur encause.fr
