Comment documenter le code Python à l'aide de Docstrings

Sans une documentation appropriée, il peut être difficile de comprendre, de maintenir et de déboguer votre code. En Python, vous pouvez utiliser des 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 un 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 les détails d'implémentation ou les 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 sa mise en œuvre, mais doivent comprendre ce qu'il fait et comment l'utiliser.

Comment écrire des Docstrings

Vous incluez généralement des docstrings au début du bloc de code que vous souhaitez documenter. Vous devez les mettre entre guillemets triples (). Vous pouvez écrire des docstrings sur une ligne ou des docstrings multilignes.

Les docstrings d'une ligne conviennent au code simple qui ne nécessite pas beaucoup de documentation.

Vous trouverez ci-dessous un exemple de fonction appelée multiplier. La docstring explique que la fonction multiplier prend deux nombres, les multiplie et renvoie le résultat.

définitivementmultiplier(un B):
Multiplie deux nombres et renvoie le résultat
retour un B

Utilisez des docstrings multilignes pour un code plus complexe nécessitant une documentation détaillée.

Considérez la classe de voiture suivante :

classeVoiture:

 UN classereprésentantunvoitureobjet.
 Les attributs:
 kilométrage (flottant): le kilométrage actuel de la voiture.
 Méthodes :
 drive (miles): Conduit la voiture pour le nombre de miles indiqué.

définitivement__init__(auto, kilométrage):
 self.mileage = kilométrage
définitivementconduire(auto, miles):

 Conduit la voiture pour le nombre de miles indiqué.
 Arguments :
 miles (float): Le nombre de miles à parcourir.
 Retour:
Aucun

 self.mileage += miles

La docstring de la classe ci-dessus décrit ce que la classe représente, ses attributs et ses méthodes. Pendant ce temps, les docstrings de la méthode drive fournissent des informations sur ce que fait la méthode, les arguments qu'elle attend et ce qu'elle renvoie.

Cela permet à toute personne travaillant avec cette classe de comprendre plus facilement comment l'utiliser. Les autres avantages de l'utilisation de docstrings incluent :

• Maintenabilité du code: en fournissant une description claire du fonctionnement du code, les docstrings aident les développeurs à modifier et à mettre à jour le code sans introduire d'erreurs.
• Collaboration facilitée: lorsque plusieurs développeurs collaborent sur la même base de code, par exemple avec le Outil de partage en direct de Visual Studio— les docstrings permettent aux développeurs de documenter le code de manière cohérente afin que tous les membres de l'équipe puissent le comprendre.
• Amélioration de la lisibilité du code: les Docstrings fournissent un résumé de haut niveau de ce que fait le code, ce qui permet toute personne lisant le code pour comprendre rapidement son objectif sans parcourir tout le code bloc.

Formats de chaîne de documentation

Une bonne docstring doit décrire ce que fait un morceau de code, les arguments qu'il attend et les détails d'implémentation si nécessaire. Il devrait notamment inclure tous les cas extrêmes dont toute personne utilisant le code devrait être consciente.

Un format de chaîne de documentation de base comporte les sections suivantes :

• Ligne de résumé: Un résumé d'une ligne de ce que fait le code.
• Arguments: informations sur les arguments attendus par la fonction, y compris leurs types de données.
• Valeur de retour: informations sur la valeur de retour de la fonction, y compris son type de données.
• Raises (facultatif): informations sur les exceptions que la fonction peut déclencher.

Ce n'est qu'un format de base car il existe d'autres formats que vous pouvez choisir pour baser vos docstrings. Les plus populaires sont Epytext, reStructuredText (également connu sous le nom de reST), NumPy et Google docstrings. Chacun de ces formats a sa propre syntaxe, comme illustré dans les exemples suivants :

Épytexte

Une docstring qui suit le format Epytext :

définitivementmultiplier(un B):

 Multipliez deux nombres ensemble.
 @param a: Le premier nombre à multiplier.
 @tapez un: entier
 @param b: Le deuxième nombre à multiplier.
 @type b: entier
 @retour: Le produit des deux nombres.
 @rtype: entier

retour un B

texte restructuré (reST)

Une docstring qui suit le format reST :

définitivementmultiplier(un B):

 Multipliez deux nombres ensemble.
 :param a: Le premier nombre à multiplier.
 :tapez un: entier
 :param b: Le deuxième nombre à multiplier.
 :type b: entier
 :retour: Le produit des deux nombres.
 :rtype: int

retour un B

NumPy

Une docstring qui suit le format NumPy :

définitivementmultiplier(un B):

 Multipliez deux nombres ensemble.
 Paramètres

 un: entier
 Le premier nombre à multiplier.
 b: entier
 Le deuxième nombre à multiplier.
 Retour

 entier
 Le produit des deux nombres.

retour un B

Google

Une docstring qui suit le format Google :

définitivementmultiplier(un B):

 Multipliez deux nombres ensemble.
 Arguments :
 a (int): Le premier nombre à multiplier.
 b (int): Le deuxième nombre à multiplier.
 Retour:
 int: Le produit des deux nombres.

retour un B

Bien que les quatre formats de chaîne de documentation fournissent une documentation utile pour la fonction de multiplication, les formats NumPy et Google sont plus faciles à lire que les formats Epytext et reST.

Comment inclure des tests dans les Docstrings

Vous pouvez inclure des exemples de test dans vos docstrings à l'aide du module doctest. Le module doctest recherche dans la docstring du texte qui ressemble à des sessions Python interactives, puis les exécute pour vérifier qu'elles fonctionnent comme elles le devraient.

Pour utiliser les doctests, incluez les exemples d'entrées et les sorties attendues dans la docstring. Vous trouverez ci-dessous un exemple de la manière dont vous procéderiez :

définitivementmultiplier(un B):

 Multipliez deux nombres ensemble.
 Paramètres

 un: entier
 Le premier nombre à multiplier.
 b: entier
 Le deuxième nombre à multiplier.
 Retour

 entier
 Le produit des deux nombres.
 Exemples

 >>> multiplier(2, 3)
6
 >>> multiplier(0, 10)
0
 >>> multiplier(-1, 5)
-5

retour un B

Le Exemples contient trois appels de fonction avec des arguments différents et spécifie la sortie attendue pour chacun. Lorsque vous exécutez le module doctest comme indiqué ci-dessous, il exécute les exemples et compare la sortie réelle à la sortie attendue.

python -m doctest multiplier.py

S'il y a des différences, le module doctest les signale comme des échecs. L'utilisation de doctests avec des docstrings comme celle-ci vous aide à vérifier que le code fonctionne comme prévu. Notez que les doctests ne remplacent pas des tests plus complets tests unitaires et tests d'intégration pour votre code Python.

Comment générer de la documentation à partir de Docstrings

Vous avez appris les bases de l'utilisation des docstrings pour documenter votre code Python et l'importance d'une documentation de haute qualité. Pour monter d'un cran, vous pouvez générer de la documentation pour vos modules et fonctions à partir de leurs docstrings respectifs.

L'un des générateurs de documentation les plus populaires que vous pouvez utiliser est Sphinx. Il prend en charge le format docstring reST par défaut, mais vous pouvez le configurer pour qu'il fonctionne avec le format Google ou NumPy.