Modèles de Docstring les plus courants en Python

Documenter le code est une bonne habitude, et les développeurs et programmeurs en herbe devraient prendre l’habitude de documenter leur code dans les premières phases de leur parcours de codage.

Documenter un code source améliore la lisibilité et la gestion du code source et le rend extrêmement facile à comprendre pour les nouveaux contributeurs au code source.

Les docstrings sont des littéraux de chaîne écrits dans les codes sources. Ils agissent comme des commentaires ou de la documentation pour des morceaux de code. Les docstrings sont utilisées pour décrire les classes, les fonctions et parfois même les fichiers.

En d’autres termes, une docstring agit comme des métadonnées sur les extraits de code. Une docstring contient toutes les informations pertinentes sur ce qu’ils décrivent. Pour une classe, il contient des informations sur :

• la classe
• fonctions de classe
• attributs de classe.

Pour les fonctions, il contient des détails sur :

• paramètres
• types de données des paramètres
• valeurs par défaut des paramètres
• brèves descriptions des paramètres
• ce que la fonction retourne
• type de données de ce qui est renvoyé par la fonction
• les erreurs et les exceptions que la fonction soulève et de courtes descriptions à propos

Il existe plusieurs modèles de docstring que les développeurs Python professionnels utilisent pour documenter leur code.

Au lieu d’utiliser ceux existants, on peut créer leur modèle de docstring. Pourtant, cette décision dépend uniquement du développeur individuel ou de l’équipe de développeurs.

Cet article abordera les meilleurs modèles de docstring pour le langage de programmation Python.

Modèles de docstring en Python

Voici quelques-uns des meilleurs modèles de docstring couramment utilisés dans l’industrie par les professionnels de Python.

Modèle Epytext

Le modèle Epytext est un modèle de docstring similaire au JavaDoc. Il fait partie de l’outil Epydoc utilisé pour générer de la documentation pour les modules Python à l’aide de leurs docstrings. Voici un exemple du modèle Epytext.

"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

@param parameter1: this is the first parameter.
@param parameter2: this is the second parameter.
@return: this is a description of what is returned by the function.
@raise KeyError: raises an exception.
@raise TypeError: raises an exception.
"""

Une brève description de la fonction est fournie en haut.

Tous les paramètres de la fonction sont écrits à l’aide du mot-clé @param. Une explication de ce qui est renvoyé par la fonction est écrite à côté du mot-clé @return.

Si la fonction lève des erreurs ou des exceptions, elles sont écrites à l’aide du mot-clé @raise.

Modèle reST

Le reSt ou reStructuredText est un modèle de docstring utilisé par le Sphinx, un outil pour générer de la documentation pour le langage de programmation Python. Ce modèle est l’un des modèles de docstrings les plus utilisés dans l’industrie informatique.

Cette méthode est également utilisée comme format de sortie dans Pyment, un outil pour aider les programmeurs Python à rédiger une documentation de code améliorée à l’aide de docstrings. Cet outil est utile lorsque le code est partiellement documenté ou ne contient pas de docstrings.

L’IDE JetBrains PyCharm ou l’environnement de développement intégré utilise également le modèle reST. Voici un exemple du modèle reST.

"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

:param parameter1: this is the first parameter.
:param parameter2: this is the second parameter.
:return: this is a description of what is returned by the function.
:raise KeyError: raises an exception.
:raise TypeError: raises an exception.
"""

Semblable au modèle Epytext, tout est identique pour ce modèle, sauf qu’il utilise deux points ou : comme préfixe pour les mots-clés au lieu du signe arobase ou @ dans le cas du modèle Epytext.

Une description concise ou complète de la méthode se trouve en haut. Tous les paramètres sont placés à côté du mot-clé :param. Une explication de ce qui est renvoyé par la méthode est écrite à côté du mot-clé :return.

Et, les détails de toutes les erreurs sont placés à côté du mot-clé :raise.

Modèle Google

Un autre modèle sur la liste est le modèle Google. Techniquement, son nom n’est pas le modèle de Google, mais c’est un modèle que Google a développé.

C’est un modèle propre qui organise les détails sous des titres. L’outil Sphinx est également capable de reconnaître ce modèle et de générer de la documentation.

Ce modèle est également l’un des modèles les plus docstrings. Voici un exemple du modèle Google.

"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Args:
    parameter1: this is the first parameter.
    parameter2: this is the second parameter.

Returns:
    this is a description of what is returned by the function.

Raises:
    KeyError: raises an exception.
    TypeError: raises an exception.
"""

Comme les modèles précédents, une description succincte de la méthode se trouve en haut.

La description est suivie d’en-têtes tels que Args, Returns et Raises. Sous la rubrique Args, tous les paramètres et détails, tels que leur type et leurs valeurs par défaut, sont placés.

Une description de ce qui est renvoyé par la fonction est placée sous l’en-tête Returns. Enfin, les erreurs ou exceptions et leurs détails sont écrits sous la rubrique Raises.

Modèle Numpydoc

Le module numpy a ses modèles de docstring connus sous le nom de modèle Numpydoc.

Ce modèle est similaire au modèle Google et il est reconnu par l’outil Sphinx. Semblable au modèle de Google, les informations sont organisées sous des rubriques.

Voici un exemple du modèle Numpydoc.

"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Parameters
----------
parameter1 : int
    this is the first parameter.
parameter2 : str, "default value"
    this is the second parameter.

Returns
-------
string
    returns a string value.

Raises
------
KeyError
    raises an exception.
TypeError
    raises an exception.
"""

La description de la méthode est écrite en haut. D’autres détails sur la méthode sont organisés sous les rubriques : Parameters, Returns et Raises.

Tous les détails sur les paramètres, y compris leur valeur par défaut, le type de valeur, etc., sont placés sous la rubrique Parameters. Tous les détails sur ce qui est renvoyé par la fonction, y compris le type de données, se trouvent sous l’en-tête Returns.

Enfin, des informations sur les erreurs ou exceptions et certaines descriptions sont écrites sous la rubrique Raises.