GUI Modeler -
SNIper
Guide de
programmation JAVA
Version <1.0>
Historique des révisions
|
Date |
Version |
Description |
Auteur |
|
<15/12/2001> |
<1.0> |
Création |
ISI3_BE1 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Table des matières
1. Introduction 4
1.1 Objectif 4
1.2 Portée 4
1.3 Références 4
1.4 Contenu du document 4
2. Généralités 4
3. Les conventions de nommage 4
3.1 Conventions générales 4
3.1.1 Noms de types 4
3.1.2 Noms de variables 4
3.1.3 Noms de constantes 5
3.1.4 Noms de méthodes 5
3.1.5 Noms de classes 5
3.1.6 Acronymes 5
3.1.7 Noms de variables significatifs 5
3.1.8 Méthodes d’un objet 5
3.2 Conventions particulières 5
3.2.1 Liste d’objets 5
3.2.2 Nombre d’objets 5
3.2.3 Identifiant d’un objet 5
4. Les paquetages 6
4.1.1 Sous parties 6
4.1.2 Noms de paquetages 6
4.1.3 Préfixe 6
5. Les instructions 6
5.1 Les instructions « package » et « import » 6
5.1.1 L’instruction « package » 6
5.1.2 L’instruction « import » 6
5.2 Les classes et interfaces 6
5.2.1 Architecture d’un fichier 6
5.3 Les variables 6
5.3.1 Déclaration 6
5.3.2 Initialisation 6
6. Indentation et commentaires 7
6.1 Indentation 7
6.2 Commentaires 7
6.2.1 Convention 7
6.2.2 Génération de la documentation 7
6.2.3 Pour une classe 7
6.2.4 Pour une méthode 7
6.2.5 Pour un attribut 7
7. Recommandations 8
Guide de programmation
JAVA
Ce document décrit les règles à suivre durant les phases de codage du
logiciel SNIper.
Les règles décrites dans ce document permettent une homogénéité du code
produit améliorant ainsi la lisibilité de celui-ci.
[A
brief description of the scope of the Programming Guidelines; what
Project(s) it is associated with and anything else that is affected or
influenced by this document.]
[This subsection provides a complete list of
all documents referenced elsewhere in the Programming Guidelines.
Identify each document by title, report number if applicable, date, and
publishing organization. Specify the sources from which the references can be obtained.
This information may be provided by reference to an appendix or to another
document.]
Ce document regroupe les règles de nommage des
variables, les règles de nommage des fichiers, les règles d’organisation des
fichiers, les règles de codage et les recommandations.
Les noms de méthodes doivent être en Français sauf
pour les méthodes d’accès aux attributs (getter et setter) ou les méthodes
renvoyant un booléen (is…). Dans ces deux cas, le préfixe cité
(« get » pour obtenir la valeur d’un attribut, « set » pour
modifier la valeur d’un attribut et « is » pour une méthode
retournant un booléen) sera obligatoirement utilisé :
calculerNbPoints()
getNom()
isVide()
Les noms d’attributs et commentaires de codes doivent être exclusivement en
Français.
Les noms pour les types doivent être déclarés et
utilisés en "Mixed Case" en commençant par une majuscule :
Line, FilePrefix
Les noms de variables doivent être déclarés et
utilisés en "Mixed Case" en commençant par une minuscule :
line, filePrefix
Cette convention permet de différencier facilement les types des variables
:
Line line
Les noms représentant des constantes (final variables)
doivent être en majuscules et utiliser des underscores comme séparateurs :
MAX_ITERATIONS, COLOR_RED
Les noms de méthodes doivent être des verbes et
écrits en "Mixed Case" et
commencer par une minuscule :
calculerLargeurTotale();
Le nom de la classe commence par une majuscule et
doit faire référence au nom de la classe dont elle hérite :
Public
class BoutonOuvrir extends Button ;
Public
class ExceptionVide extends Exception;
Les acronymes ne doivent pas être écrits en
majuscules lorsqu'ils sont utilisés comme des noms :
exporterSourceHtml(); // pas : exporterSourceHTML();
ouvrirLecteurDvd(); // pas : ouvrirLecteurDVD();
Les variables utilisées tout au long d’une méthode
doivent avoir des noms complets et significatifs. Les variables utilisées seulement
dans un bloc (ex : pour une boucle) peuvent avoir des noms courts :
· variables largement utilisées : largeurTotalePage
·
variables utilisées
localement : i,j,k,l,m pour des entiers, c et d pour des
caractères.
Le nom de l'objet est implicite et doit être évité
dans le nom de méthodes :
ligne.getLongueur(); // pas : ligne.getLongueurLigne()
Pour une liste d'objets on utilisera le préfixe « liste »
suivi du nom de l’objet au pluriel :
couleur (un objet) à listeCouleurs (une liste d'objets)
Les variables qui représentent un nombre d'objets sont composées du préfixe
« nb » suivi du nom de l’objet au pluriel :
nbLignes, nbPoints
Le préfixe « id » est utilisé pour indiquer un identifiant unique
d'objet :
idEmploye, idTable
Créer un nouveau paquetage pour chacune des sous parties du projet.
Utiliser des répertoires pour stocker ces paquetages en accord avec la
convention des paquetages.
Les noms de paquetages doivent être en minuscules :
guimodeler.sniper.ui
Tous les noms de paquetage seront préfixés
par « guimodeler ».
L’instruction package est la première du fichier. Chaque fichier
appartient à un paquetage.
L’instruction import suit l’instruction package.
L’instruction import présente de manière triée les paquetages en commençant par
les plus fondamentaux et en les regroupant de manière logique.
L’utilisation de * pour importer toutes les
classes d’un même paquetage est déconseillée :
import java.io.File;
import javax.swing.Box;
Les déclarations de classes et d’interfaces doivent être présentées de la
manière suivante :
1.
Documentation de la
classe / interface
2.
Instruction class /
interface
3.
Attributs de la
classe
4.
Les constructeurs
5.
Les autres méthodes
Les attributs de classe ne doivent pas être
déclarées « public ». Il est nécessaire de les déclarer
« private » et de créer des méthodes permettant d’y accéder.
Les variables doivent être initialisées au moment de leur déclaration.
L’indentation de base est de 4.
Toutes les classes et les méthodes seront
documentées en utilisant les conventions « Javadoc » :
/**
* Description de la methode
* @param Nom_Param, Description du parametre
* @return Type_Param, Type de retour de la methode si retour il y a
* @exception Type_Exception, Description de l’exception levée
*/
Ligne de commande pour générer la documentation :
javadoc -d apidoc_repertoire @packages
où packages est le nom d'un fichier texte qui contient la liste de tous les
packages à générer.
Chaque classe commencera par le commentaire
suivant :
/**
* descriptif de la classe
* @see Personne Personne
* @copyright Simulog
*/
Cette entête permettra la génération d’une page
HTML facilitant la navigation entre les différentes classes en rapport.
Chaque méthode comencera par le commentaire suivant :
/**
* descriptif de la méthode (fonctionnalité de la methode + mini
* algorithme si elle est compliquée)
* @param number : descriptif de la signification de l'attribut et
* @return java.lang.Object : descriptif de l'objet retourné
* @exception Exception
*/
Chaque attribut aura ce commentaire
/**
* Descriptif de l'attribut. Plage de valeur et valeur initiale
*/
· aucun * dans les imports
· écrire une méthode main pour chacune des classes testables
· le « main » de l'application doit être dans une classe séparée Main
· éviter de déclarer des attributs comme public. Implantez plutôt pour un attribut « nom », deux méthodes : setNom() et getNom()
·
initialiser les
objets qui peuvent retourner une Enumeration (Vector, HashTable...) avec un
objet vide (ex : Vector monVecteur = new Vector()) et non pas avec
« null »
· déclarer toutes les méthodes « public » comme synchronized si elles peuvent être utilisées dans un contexte concurrent (threads)
· ne déclarer les variables locales qu'à l'endroit où elles sont réellement nécessaires
· affecter « null » à toutes les références qui ne sont plus utilisées