Projet

Général

Profil

DocumentationCodeBonnesPratiques » Historique » Version 2

Gwenael Remond, 12/12/2012 11:10

1 1 Emmanuel GARETTE
h1. DocumentationCodeBonnesPratiques
2 1 Emmanuel GARETTE
3 1 Emmanuel GARETTE
h2. Généralité
4 1 Emmanuel GARETTE
5 1 Emmanuel GARETTE
* La documentation technique doit être en anglais.
6 1 Emmanuel GARETTE
* Elle est placé dans les docstrings du code.
7 1 Emmanuel GARETTE
8 1 Emmanuel GARETTE
h2. Description du module
9 1 Emmanuel GARETTE
10 1 Emmanuel GARETTE
La docstring du module est placée en haut du fichier.
11 1 Emmanuel GARETTE
12 1 Emmanuel GARETTE
La docstring doit contenir :
13 1 Emmanuel GARETTE
14 2 Gwenael Remond
* la licence du code 
15 2 Gwenael Remond
16 2 Gwenael Remond
<pre>
17 2 Gwenael Remond
###########################################################################
18 2 Gwenael Remond
#
19 2 Gwenael Remond
# EOLE
20 2 Gwenael Remond
# Copyright Pole de Competence EOLE  (Ministere Education - Academie Dijon)
21 2 Gwenael Remond
# Licence CeCill  http://www.cecill.info/licences/Licence_CeCILL_V2-fr.html
22 2 Gwenael Remond
# eole@ac-dijon.fr
23 2 Gwenael Remond
#
24 2 Gwenael Remond
###########################################################################
25 2 Gwenael Remond
</pre>
26 2 Gwenael Remond
27 1 Emmanuel GARETTE
* description rapide en une phrase du module ;
28 1 Emmanuel GARETTE
* description avancée qui explique le rôle du module ;
29 1 Emmanuel GARETTE
* des exemples simples d'utilisation.
30 1 Emmanuel GARETTE
31 1 Emmanuel GARETTE
Les exemples peuvent être un prompt :
32 1 Emmanuel GARETTE
33 1 Emmanuel GARETTE
<pre>
34 1 Emmanuel GARETTE
    >>> is_locked()
35 1 Emmanuel GARETTE
    True
36 1 Emmanuel GARETTE
</pre>
37 1 Emmanuel GARETTE
38 1 Emmanuel GARETTE
ou une portion de code :
39 1 Emmanuel GARETTE
40 1 Emmanuel GARETTE
<pre>
41 1 Emmanuel GARETTE
    ::
42 1 Emmanuel GARETTE
43 1 Emmanuel GARETTE
        from toto.titi import is_locked
44 1 Emmanuel GARETTE
45 1 Emmanuel GARETTE
        toto()
46 1 Emmanuel GARETTE
        is_locked()
47 1 Emmanuel GARETTE
</pre>
48 1 Emmanuel GARETTE
49 1 Emmanuel GARETTE
h2. Docstring des méthodes
50 1 Emmanuel GARETTE
51 1 Emmanuel GARETTE
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).
52 1 Emmanuel GARETTE
53 1 Emmanuel GARETTE
La docstring doit contenir :
54 1 Emmanuel GARETTE
55 1 Emmanuel GARETTE
* description rapide en une phrase de la méthode ;
56 1 Emmanuel GARETTE
* si nécessaire une description avancée qui explique le rôle du module ;
57 1 Emmanuel GARETTE
* si nécessaire des exemples simples d'utilisation.
58 1 Emmanuel GARETTE
* les paramètres de la façon suivante (xxx étant le nom du paramètre et yyyyyy la description) :
59 1 Emmanuel GARETTE
60 1 Emmanuel GARETTE
<pre>
61 1 Emmanuel GARETTE
    :param xxx: yyyyyy
62 1 Emmanuel GARETTE
</pre>
63 1 Emmanuel GARETTE
64 1 Emmanuel GARETTE
Si nécessaire les valeurs de retour (yyyyyy étant la description) :
65 1 Emmanuel GARETTE
66 1 Emmanuel GARETTE
<pre>
67 1 Emmanuel GARETTE
    :return: yyyyyy
68 1 Emmanuel GARETTE
</pre>
69 1 Emmanuel GARETTE
70 1 Emmanuel GARETTE
h2. Docstring des classes
71 1 Emmanuel GARETTE
72 1 Emmanuel GARETTE
A faire