DocumentationCodeBonnesPratiques¶

Généralité¶

• La documentation technique doit être en anglais.
• Elle est placé dans les docstrings du code.

Description du module¶

La docstring du module est placée en haut du fichier.

La docstring doit contenir :

• description rapide en une phrase du module ;
• description avancée qui explique le rôle du module ;
• des exemples simples d'utilisation.

Les exemples peuvent être un prompt :

    >>> is_locked()
    True

ou une portion de code :

    ::

        from toto.titi import is_locked

        toto()
        is_locked()

Docstring des méthodes¶

Seules les méthodes publiques (qui ne commencent pas par "_") seront mises dans la documentation (mais les méthodes privées sont aussi à documentée).

La docstring doit contenir :

• description rapide en une phrase de la méthode ;
• si nécessaire une description avancée qui explique le rôle du module ;
• si nécessaire des exemples simples d'utilisation.
• les paramètres de la façon suivante (xxx étant le nom du paramètre et yyyyyy la description) :

    :param xxx: yyyyyy

Si nécessaire les valeurs de retour (yyyyyy étant la description) :

    :return: yyyyyy

Docstring des classes¶

A faire