PEP257 ou les conventions des docstrings

Le but de ce PEP est de standardiser la structure de haut niveau des docstrings : ce qu'ils doivent contenir et comment le dire (sans toucher à la syntaxe du balisage dans les docstrings). Le PEP contient des conventions, et non des lois ou une syntaxe.

"Une convention universelle fournit tout ce qui est maintenabilité, clarté, cohérence, et une base pour de bonnes habitudes de programmation aussi. Ce qu'elle ne fait pas, c'est insister pour que vous la suiviez contre votre volonté. C'est Python !"

-- Tim Peters sur comp.lang.python, 2001-06-16

Si vous violez ces conventions, le pire que vous obtiendrez sera un mauvais regard. Mais certains logiciels (tels que le système de traitement des chaînes de caractères Docutils) connaissent les conventions, et les respecter vous permettra d'obtenir les meilleurs résultats.

Que sont les docstrings ?

Une docstring est une chaîne de caractères littérale qui apparaît comme première déclaration dans un module, une fonction, une classe ou une définition de méthode. Une telle docstring devient l'attribut spécial __doc__ de cet objet.

Tous les modules devraient normalement avoir des docstrings, et toutes les fonctions et classes exportées par un module devraient également avoir des docstrings. Les méthodes publiques (y compris le constructeur __init__) doivent également avoir des docstrings. Un paquet peut être documenté dans la docstring du module du fichier __init__.py dans le répertoire du paquet.

Les chaînes de caractères qui apparaissent ailleurs dans le code Python peuvent également servir de documentation. Ils ne sont pas reconnus par le compilateur de bytecode Python et ne sont pas accessibles en tant qu'attributs d'objet d'exécution (c'est-à-dire qu'ils ne sont pas affectés à __doc__), mais deux types de docstrings supplémentaires peuvent être extraits par des outils logiciels :

• Les littéraux de chaîne de caractères apparaissant immédiatement après une simple affectation au niveau supérieur d'un module, d'une classe ou de la méthode __init__ sont appelés docstrings d'attributs.
• Les chaînes de caractères qui se trouvent immédiatement après une autre chaîne de caractères sont appelées chaînes de caractères supplémentaires.

Pour des raisons de cohérence, utilisez toujours """des guillemets doubles triples"" autour des chaînes de caractères. Utilisez les """triples guillemets bruts"" si vous utilisez des antislashs dans vos chaînes de caractères. Pour les docstrings Unicode, utilisez u """chaînes Unicode à triple guillemets""".

Il existe deux formes de docstrings : les docstrings d'une ligne et les docstrings multilignes.

Les docstrings d’une ligne

Les phrases d'une ligne sont pour les cas vraiment évidentes. Elles doivent vraiment tenir sur une ligne. Par exemple :

def kos_root() :
    """Retourne le chemin du répertoire racine de KOS."""
    global _kos_root
    if _kos_root : return _kos_root
    # ...

Des guillemets triples sont utilisés même si la chaîne tient sur une seule ligne. Cela permet de l'étendre facilement par la suite.

Les guillemets fermants sont sur la même ligne que les guillemets ouvrants. C'est mieux pour les phrases d'une ligne.

Il n'y a pas de ligne vierge avant ou après la chaîne de caractères.

La docstring est une phrase qui se termine par un point. Elle prescrit l'effet de la fonction ou de la méthode en tant que commande ("Fais ceci", "Renvoie cela"), et non en tant que description ; par exemple, n'écrivez pas "Renvoie le nom de chemin ...".

La docstring d'une ligne ne doit PAS être une "signature" répétant les paramètres de la fonction/méthode (qui peuvent être obtenus par introspection). Ne le faites pas :

def function(a, b) :
    """function(a, b) -> liste"""

Ce type de docstring n'est approprié que pour les fonctions C (comme les built-ins), où l'introspection n'est pas possible. Cependant, la nature de la valeur de retour ne peut pas être déterminée par introspection, elle doit donc être mentionnée. La forme préférée pour une telle docstring serait quelque chose comme :

def function(a, b) :
    """Faire X et retourner une liste."""

(Bien sûr, "Faire X" devrait être remplacé par une description utile !)

Docstrings multiligne