Normaliser les codes sources en langage Python
Ce document est une proposition de convention de codage pour les projets utilisant le langage Python. L'application de cette convention consiste à respecter les points précisés dans celle-ci et à se baser sur le modèle de document fourni.
La présente convention prend en compte l'utilisation des logiciels suivants :
- Epydoc pour générer la documentation du code ;
- CVS pour gérer les versions de codes sources.
- la documentation doit se trouver à l'intérieur des docstring ;
- la documentation située dans les docstring respecte le format d'Epydoc : Epytext Markup Language ;
- les codes sources sont sur 80 colonnes ;
- les codes sources ne contiennent pas de caractère tabulation ;
- l'indentation est réalisée avec quatres caractères espaces.
Un modèle de code source est présenté ci-dessous. Les champs soulignés sont à complèter.
1 #!/usr/bin/env python
2 # -*- mode:python ; tab-width:4 -*- ex:set tabstop=4 shiftwidth=4 expandtab: -*-
3
4 ################################################################################
5 # PROJECT: projet - FILE: fichier - CREATION: date-creation
6 # licence
7 # $Id$
8 ################################################################################
9 """
10 commentaire
11
12 @version: version
13 @author: U{auteur}
14 """
15
16
17 import onemodule
18
19
20 ################################################################################
21 class MyClass:
22 """
23 commentaire
24 """
25
26 ############################################################################
27 def __init__(self, arg):
28 """
29 commentaire
30 @param arg: commentaire
31 """
32 [...]
33
34 ############################################################################
35 def oneMethod(self):
36 """
37 commentaire
38 """
39 [...]
40
41
42 ################################################################################
43 def main():
44 """
45 commentaire
46 """
47 [...]
Les codes sources doivent suivre le modèle précédent. Un autre exemple de code source respectant cette convention est disponible.
Les lignes blanches ne sont pas facultatives. Entre deux classes et deux fonctions, laisser deux lignes blanches. Entre deux méthodes d'une même classe, sauter une ligne.
Commencer les phrases dans les commentaires et dans les docstring par une majuscule et les terminer par un point. Accentuer et ponctuer correctement les phrases.
La deuxième ligne du modèle configure automatiquement les éditeurs vi et emacs lors de l'ouverture d'un tel fichier afin d'utiliser quatre espaces plutot que des tabulations pour l'indentation. Si vous n'utilisez pas vi, emacs ou un clone de ces derniers, configurez votre éditeur afin qu'il gère correctement l'indentation. Conservez dans tous les cas cette ligne.
Suit la description des champs à compléter figurant dans le modèle :
- projet : nom du projet auquel appartient le fichier ;
- fichier : nom physique du fichier ;
- date-creation : date de création du fichier au format américain (AAAA/MM/JJ) ;
- licence : licence sous laquelle se trouve le fichier ;
- commentaire : commentaire concernant le bloc auquel il appartient ;
- version : numéro de version respectant votre codification ;
- auteur : nom de l'auteur au format suivant :
Prénom Nom (code) <mail>; par exemple :Bob Torkards (BTO) <bob@example.com>.
Les règles de nommage suivantes doivent être respectées :
- les noms d'attributs, de variables, de méthodes et de fonctions commencent par une lettre minuscule ;
- les noms de classes commencent par une lettre majuscule ;
- les attributs sont préfixés du caractère souligné _ ;
- les variables ne sont pas préfixées du caractère souligné _ ;
- les préfixes suivants sont réservés aux noms de méthodes et sont interdits aux noms d'attributs et de variables : set, get, is ;
- les noms de méthodes et de fonctions ne contiennent pas de caractère souligné _ sauf en préfixe ou en suffixe ; une exception à cela : les callbacks GTK+.
| Epydoc : | http://epydoc.sourceforge.net |
|---|---|
| Epytext Markup Language : | http://epydoc.sourceforge.net/epytext.html |