|
CodingGuidelines
Règles de codages
Phase-Implementation IntroductionLes 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 :
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.
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.
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.
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é :
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, …).
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"
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. |