javacrim Wiki

Brought to you by: glorieux, javacrim

conventions de codage Java Edit

Authors:

Convention de codage Java

Pourquoi ?
- 20/80 : développement / maintenance
- Celui qui maintient n'est pas forcément celui qui a développé
- Augmenter la lisibilité pour permettre une reprise plus rapide du code

Convention de codage Java

Quelques rappels spécifiques [2012-11-14]

Penser à l'utilisateur

Toujours fournir une aide minimale.
Expliquer si un paramètre est requis.
Toujours distribuer un projet avec des scripts .sh et .bat (demander à un collègue pour un autre système).
De manière générale, le code envoyé doit être testé un minimum.

Penser au collègue

Toujours signer son code, si possible avec un email, mais, pas au début de la description, plutôt à la fin (cf tags javadoc http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#tag). La signature en tête de classe s'applique par défaut à toute les méthodes, signer une méthode lorsqu'il ne s'agit pas de l'auteur principal de la classe.
L'indentation n'est pas une manie, c'est une manifestation de la logique. Ne pas mélanger les tabs et les espaces, au risque de déranger les alignements pour ceux qui ne mettent pas le même nombre d'espaces par tab.
En général, pour commenter une méthode, il suffit d'un commentaire javadoc / / avant la déclaration, et de commentaires sur une ligne // en cours de code ; le commentaire multiligne / */ peut être réservé au déboguade, pour provisoirement ne pas exécuter une portion de code. Le commentaire d'une classe s'inscritjuste avant public class, la place avant la déclaration package est utilisée pour la licence. Pour une meilleure lisibilité, les commentaires commençant par // sont placés au dessus de la ligne à commenter et sont précédés d'une ligne vide. Voyez par exemple cette classe String de la machine virtuelle Java libre, openjdk, http://grepcode.com/file/repository.grepcode.com/java/root/jdk/openjdk/7-b147/java/lang/String.java#String
Assurez vous de votre chaîne unicode, dans l'éditeur et à la compilation, vous devez pouvoir inscrire les caractères accentués explicitement, et pas ~~'\u…'~~.
Avant de distribuer, nettoyer vos fichiers parasites (affichez les dossiers cachés selon votre système, nécessaire avant de partager des sources, par exemple pour subversion)
Mac : .DS_Store, __MACOSX…
Windows : .thumbs…
Linux : .bak, .~, .kate-swp…
Nommage des variables, on utilise tabRaw plutôt que tab_raw
Traiter le cas d'erreur avant le cas nominal permet d'éviter les else très loin derrière le if.
Il n'est généralement pas nécessaire d'écrire le nom développé d'une classe, comme java.io.File. Utiliser des imports, spécifique ex: import java.io.File, ou générique java.io.*. La seule raison d'utiliser les noms développés concerne les cas de conflits de nommage, exemple org.w3c.dom.Document et org.apache.lucene.document.Document.
Integer.parseInt() a un coût, il vaut mieux ne le faire qu'une fois.

Organisation du fichier

Organisation d'un fichier Java
- En-tête
  - Un commentaire de début (/* */) : Version, date et copyright
  - déclaration de paquet
  - lignes d'import
- Déclaration de classe ou interface
  - Commentaire javadoc de la classe ou interface (/** ... */)
  - déclaration de la classe ou interface
  - attributs de classes (public, protected, package puis private)
  - attributs d'instances (public, protected, package puis private)
  - constructeur(s)
  - méthodes (groupées par fonctionnalité)

Identation

Indentation recommandée : 4 espaces
- L'en-tête et jusqu'à la déclaration du nom de la classe ne sont pas indentées
- Les déclarations d'attributs et de méthodes sont indentés de 4 espaces
Eviter les lignes de + de 80 caractères
- Si la ligne dépasse les 80 caractères, essayer de passer à la ligne au bon endroit :
  - par exemple après une virgule
  - en rejetant un opérateur à la ligne
  - en réindentant la ligne rejetée

Commentaires

Commentaires de bloc (indentés et sur une ligne à part du code pour écrire un paragraphe de description) :

 /**
  * Commentaire de bloc
  */

commentaires de fin de ligne (pour ajouter un commentaire au-dessus ou sur une ligne de code, pour commenter toute une zone de code

 // Commentaire de fin de ligne

Commentaires JavaDoc (cf guide d'écriture)

 /**
  * Cette méthode calcule la somme de 2 entiers
  * @param nb1 1er entier
  * @param nb2 2nd entier
  * @return la somme des entiers passés en paramètre
  */
 int somme(int nb1, int nb2) {
     return nb1 + nb2;
 }

Déclarations

Déclarations de variables :
- Privilégier une déclaration par ligne (avec un commentaire de fin de ligne)
- Une espace ou une tabulation entre le type et le nom de la variable
- Essayer d'initialiser la variable à sa déclaration, quand c'est possible
- Le plus proche de leur initialisation et plutôt en début de bloc
Déclarations de méthodes :
- Pas d'espace entre le nom de la méthode et la parenthèse ouvrante
- Le { de début de bloc de méthode commence sur la ligne de déclaration de méthode
- Le } de fin de bloc apparait seul sur une ligne (sauf si {})
- Une ligne blanche sépare 2 méthodes

Instructions

Pas plus d'une d'une instruction simple par ligne
Instructions combinées (liste d'instructions dans un bloc { ... })
- les instructions figurant dans un bloc ont un niveau d'identation supplémentaire
- Le signe de début de bloc (« { ») doit se retrouver en fin de ligne
- Le signe de fin de bloc (« } ») sur une nouvelle ligne à l'aplomb de l'instruction de début de bloc
- On utilisera des {} pour entourer les instructions (mêmes simples) dès lors qu'elles apparaissent dans une structure de contrôle
Les instructions return ne devraient pas être suivies de parenthèses

Structures de contrôle

Formatage des structures if-else, if else-if else :

if (condition) {
    instructions;
}

if (condition) {
    instructions;
} else {
    instructions;
}

if (condition) {
    instructions;
} else if (condition) {
    instructions;
} else {
    instructions;
}

Formatage des boucles

for (initialisation; condition; increment) {
    instructions;
}
for (initialisation; condition; increment);

while (condition) {
    instructions;
}
while (condition);

do {
    instructions;
} while (condition);

Switch

~~~~~
:::java
switch (condition) {
case ABC:
instructions;
// explication si pas de break
case DEF:
instructions;
break;
case GHI:
instructions;
break;

// ...

default:
instructions;
break; // Inutile mais prudent
}

try ... catch

:::java
try {
instructions;
} catch (Exception e) {
instructions;
}

try {
instructions;
} catch (Exception e) {
instructions;
} finally {
instructions;
}
~~~~

Espaces

2 lignes vides pour séparer les différentes sections d'un fichier source
1 ligne vide
- entre chaque méthode
- entre la déclaration des variables locales et la première instruction
- avant un bloc ou un commentaire sur une ligne
- entre les sections logiques d'une méthode
espaces
- après une parenthèse fermante
- pas d'espace entre nom de méthode et parenthèse ouvrante
- une espace autour de chaque opérateur (+, /, -, *...) sauf :
  - les opérateurs unaires
  - incrément/décrément
- une espace après chaque expression apparaissant dans une boucle for
- une espace après un cast

Conventions de nommage

Pour identifier plus facilement la nature des identifiants utilisés dans le code source
paquets :
- minuscules, ASCII 7bits
- le nom de domaine à l'envers puis toutes les subdivisions nécessaires
classes : commence par une majuscule suivie de minuscules (class Image, class AnalyseTexte), on utilise des noms
interfaces : même conditions que les classes
méthodes : on utilise des verbes, on commence par une minuscule et on met en majuscule chaque initiale de mots suivants (indexOf(), getLength())
variables : même convention minuscule/majuscule que pour les méthodes.
- On utilise de préférence un terme parlant
- les noms i, j, k, m pour les compteurs de boucle sont acceptés
- les noms c, e, d sont acceptés pour des variables caractères
constantes : en majuscules en utilisant le souligné (_) pour séparer les mots

Bonnes pratiques

Ne pas exposer publiquement les attributs de classe et d'instance sans raison valable
Éviter d'appeler une méthode de classe sur une instance
Éviter d'écrire des valeurs numériques dans le code sans les déclarer en constantes
Éviter les assignations multiples sur une même ligne
Éviter les assignations au cœur d'expression
Ne pas hésiter à utiliser des parenthèses pour clarifier une expression complexe

Remplacer

if (expression) {
    return true;
} else {
    return false;
}

par

return expression;