My favorites | Sign in
Project Home Downloads Wiki Issues Source
READ-ONLY: This project has been archived. For more information see this post.
Search
for
CodingGuidelines  
Règles de codages
Phase-Implementation
Updated Apr 3, 2012 by th.frits...@gmail.com

Introduction

Les règles de codage sont un ensemble de règles à suivre pour uniformiser les pratiques de développement logiciel, diffuser les bonnes pratiques de développement et éviter les erreurs de développement « classiques » au sein d’un groupe de développeurs.

Les règles de codage s’articulent autour de plusieurs thèmes, les plus courants étant :

  • Le nommage et l’organisation des fichiers du code source
  • L’indentation ou le style d’indentation
  • Les conventions de nommage, ou règles de nommage
  • Les commentaires et documentation du code source
  • Recommandations sur la déclaration des variables
  • Recommandations sur l’écriture des instructions, des structures de contrôle et l’usage des parenthèses dans les expressions
(cf. http://fr.wikipedia.org/wiki/Règles_de_codage

1. Le nommage et l'organisation des fichiers et du code source

Comment organisons nous nos fichiers sources ?

Les fichiers sources sont stockés dans le répertoire src du projet. Les binaires sont enregistrés dans le répertoire bin. Nous créons des packages suivants la syntaxe Sun, c'est-à-dire avec aucune majuscule (hormis dans le nom des classes). Quelle convention de nommage utilisons nous pour ceux-ci ?

Les fichiers sources portent le nom de la classe écrite à l'intérieur.

2. L'indentation ou le style d'indentation

Comment indenterons nous le code source ?

L'indentation est basée sur 4 espaces (et non pas un tabulation, par soucis d'intercompatibilité entre les différents logiciels/OS).

Chaque bloc nécessite un niveau d'indentation supplémentaire. Les blocs sont définis par une ouverture de fonction, une condition, ou une boucle. Il sera également nécessaire d'indenter les instructions écrites sur plusieurs lignes. La 1ère suivra l'indentation actuelles, mais les suivantes seront indentées d'un nouveau cran.

3. Les conventions de nommage

Comment seront organisées nos classes ?

Nous créons des packages suivants la syntaxe Sun, c'est-à-dire avec aucune majuscule (hormis dans le nom des classes).

Comment devons nous nommer nos classes ?

Nos classes doivent être déclarées avec une syntaxe « CamelCase ». Elles ne doivent pas contenir d'autres caractères.

Les classes abstraites doivent immanquablement être préfixées du mot Abstract, ou avoir comme suffixe Factory (AbstractPersonne, VoitureFactory, …).

Les interfaces sont toujours précédées de la lettre « I » (i majuscule).

De quelle façon sont écrites les méthodes ?

Le nom des méthodes sont écrites dans le style « lowerCamelCase », elles ne doivent pas contenir d'autres caractères.

4. Les commentaires et documentation du code source

De quelle façon commentons nous notre code ?

Le code sera nécessairement commenté afin de permettre à plusieurs personnes de développer aux mêmes endroits. Cela fait parti de la communication au sein de l'équipe.

Les parcelles à commenter seront, en priorité :

  • les fonctions (voir Javadoc)
  • les boucles : préciser la nature de l'objet itérant et une description minimale du traitement effectué
  • les conditions : sauf si très évidentes, mais cela peut être utile si la condition a des airs barbares

Nos commentaires doivent-ils suivre une « syntaxe » particulière ?

Nous éviterons les accents dans nos commentaires pour permettre la compatibilité entre les différents OS.

De quelle façon documenterons nous notre application ?

Un document spécifique est prévu à cet effet.

Comment allons-nous générer la documentation de notre code ?

Pour générer la documentation, nous allons utiliser javadoc. Javadoc impose une syntaxe pour les commentaires.

Quels tags Javadoc allons-nous utiliser ?

Le tag @author permet de définir qui est l'auteur du code. Le tag @param permet de définir les paramètres de la fonction/méthode Le tag @return permet de définir la valeur de retour. Le tag @throws indique les exceptions lancées par la classe. Le tag @version donne la version d'une classe et du méthode, mais il est aussi possible d'indiquer un historique des modifications en simple commentaire (quand, pourquoi, fonctionnalités ajoutées, issues résolus, …).

5. Recommandations sur la déclarations des variables

Comment reconnaîtrons nous nos variables ?

Style : "lowerCamelCase" Variable de classe : préfixée par le symbole (underscore). Variable statique : préfixée par le symbole (double underscore). Incrément : pas de "i", "j" ou autre variable exotique, préférer un "indice_machin" ou "indice_truc"

6. Recommandations sur l'écriture des instructions, des structures de contrôle et l'usage des parenthèses dans les expressions

Pour les tests, nous éviterons les conditions sur une ligne (les ternaires) afin de ne pas perturber le futur lecteur de nos classes.

Les instructions « Switch » doivent automatiquement être accompagnés d'un cas par défaut, ne serait-ce que pour contrôler entièrement toutes les possibilités.

Les méthodes ne peuvent pas déclencher plus de 3 types d'erreurs différentes. Aussi, certaines erreurs trop génériques ne peuvent pas être déclenchées, il faut savoir cibler les exceptions.

De plus, les méthodes ne doivent pas être plus longues que 150 lignes, ce qui est déjà une bonne marge. De la même manière, les méthodes internes (comme pour la gestion d'événements par exemple) ne doivent pas dépasser 50 lignes.

Powered by Google Project Hosting