Documentation des fonctions (docstrings)

Qu'est-ce qu'une docstring ? Définition et rôle

Une docstring (chaîne de documentation) est une chaîne de caractères littérale qui apparaît comme première instruction dans la définition d'une fonction, d'une classe, d'une méthode ou d'un module. Elle sert à documenter le code, c'est-à-dire à expliquer ce que fait la fonction, la classe, la méthode ou le module, comment l'utiliser, quels sont ses arguments, et quelle est sa valeur de retour (le cas échéant).

Contrairement aux commentaires ordinaires (qui commencent par `#`), les docstrings sont conservées en mémoire pendant l'exécution du programme et sont accessibles à l'aide de la fonction `help()` ou de l'attribut `__doc__`.

Les docstrings sont un élément essentiel de la documentation Python. Elles sont utilisées par :

• Les développeurs (pour comprendre le code).
• Les outils de génération de documentation (comme Sphinx).
• Les IDE (pour afficher l'aide contextuelle).
• Les linters (pour vérifier la présence et la conformité de la documentation).

Syntaxe des docstrings : chaînes multilignes

Les docstrings sont généralement des chaînes multilignes, délimitées par des triples guillemets simples (`'''`) ou doubles (`"""`). Bien que les deux types de guillemets soient valides, la convention est d'utiliser des triples guillemets doubles (`"""`).

Syntaxe de base :

def ma_fonction(arg1, arg2):
    """Description concise de la fonction.

    Description plus détaillée (facultative).

    Args:
        arg1 (type): Description de arg1.
        arg2 (type): Description de arg2.

    Returns:
        type: Description de la valeur de retour.

    Raises:
        ExceptionType: Description des exceptions levées (facultatif).

    Examples:
        >>> ma_fonction(1, 2)
        3
    """
    # Corps de la fonction
    # ...
    return valeur_de_retour

La première ligne de la docstring est généralement une phrase courte et concise qui résume le rôle de la fonction. Elle doit commencer par une majuscule et se terminer par un point.

Après une ligne vide, vous pouvez ajouter une description plus détaillée (facultative).

Ensuite, vous pouvez décrire les arguments (`Args:`), la valeur de retour (`Returns:`), et les exceptions levées (`Raises:`, facultatif).

Vous pouvez également inclure des exemples d'utilisation (`Examples:`).

Il existe différentes conventions de style pour les docstrings (reStructuredText, Google style, NumPy style). Le plus important est de choisir un style et de s'y tenir de manière cohérente dans tout votre projet.

Accéder à la docstring : help() et __doc__

Vous pouvez accéder à la docstring d'une fonction (ou d'une classe, d'une méthode, d'un module) de deux manières :

• En utilisant la fonction intégrée `help()` : `help(ma_fonction)`
• En accédant à l'attribut spécial `__doc__` : `print(ma_fonction.__doc__)`

Exemple :

def additionner(a, b):
    """Retourne la somme de deux nombres."""
    return a + b

help(additionner)
# Affiche :
# Help on function additionner in module __main__:
#
# additionner(a, b)
#     Retourne la somme de deux nombres.

print(additionner.__doc__)  # Affiche : Retourne la somme de deux nombres.

La fonction `help()` affiche la docstring de manière formatée, en incluant le nom de la fonction, sa signature (les paramètres), et la docstring elle-même. L'attribut `__doc__` contient directement la chaîne de caractères de la docstring.

Conventions de style et bonnes pratiques

Voici quelques conventions de style et bonnes pratiques pour rédiger des docstrings :

• Utilisez des triples guillemets doubles (`"""`) : C'est la convention la plus courante.
• Ecrivez une phrase concise et descriptive en première ligne : Elle doit résumer le rôle de la fonction.
• Utilisez des lignes vides pour séparer les sections : Séparez la description concise, la description détaillée, les sections `Args`, `Returns`, `Raises`, `Examples`.
• Décrivez les arguments, la valeur de retour, et les exceptions : Soyez précis sur les types et la signification de chaque paramètre.
• Utilisez un style cohérent : Choisissez un style de docstring (reStructuredText, Google, NumPy) et respectez-le dans tout votre projet.
• Gardez les docstrings à jour : Lorsque vous modifiez le code, assurez-vous que les docstrings restent pertinentes.
• Ecrivez en anglais : C'est la convention dans la communauté Python.
• Utilisez des exemples (doctests) : Les exemples dans les docstrings peuvent être exécutés automatiquement avec le module `doctest` pour vérifier qu'ils sont corrects.

Exemple de docstring respectant les conventions (style reStructuredText) :

def calculer_factorielle(n):
    """Calcule la factorielle d'un nombre entier positif.

    :param n: Le nombre entier dont on veut calculer la factorielle.
    :type n: int
    :raises TypeError: Si n n'est pas un entier.
    :raises ValueError: Si n est négatif.
    :returns: La factorielle de n.
    :rtype: int

    Exemples:
    ---------
    >>> calculer_factorielle(5)
    120
    >>> calculer_factorielle(0)
    1
    """
    if not isinstance(n, int):
        raise TypeError("n doit être un entier.")
    if n < 0:
        raise ValueError("n doit être positif ou nul.")
    if n == 0:
        return 1
    else:
        return n * calculer_factorielle(n - 1)

Docstrings pour les classes, méthodes et modules

Les docstrings ne sont pas réservées aux fonctions. Vous devez également documenter vos classes, méthodes et modules en utilisant des docstrings.

Pour une classe, la docstring doit décrire le rôle de la classe, ses attributs principaux, et ses méthodes publiques.

Pour une méthode, la docstring doit décrire le rôle de la méthode, ses arguments, sa valeur de retour, et les exceptions qu'elle peut lever (comme pour une fonction).

Pour un module, la docstring doit décrire le rôle du module et lister les classes, fonctions, et constantes qu'il exporte.

Exemple de docstring pour une classe :

class Cercle:
    """Représente un cercle dans le plan.

    Attributes:
        rayon (float): Le rayon du cercle.
    """

    def __init__(self, rayon):
        """Initialise un cercle avec un rayon donné."""
        self.rayon = rayon

    def aire(self):
        """Calcule l'aire du cercle."""
        return 3.14159 * self.rayon * self.rayon