DocumentationCodeBonnesPratiques » Historique » Version 3
« Précédent -
Version 3/34
(diff) -
Suivant » -
Version actuelle
Gwenael Remond, 12/12/2012 11:16
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 :
- la licence du code
########################################################################### # # EOLE # Copyright Pole de Competence EOLE (Ministere Education - Academie Dijon) # Licence CeCill http://www.cecill.info/licences/Licence_CeCILL_V2-fr.html # eole@ac-dijon.fr # ###########################################################################
- 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 à documenter).
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