Guide de Google pour la mise en forme du code Java

1. Introduction

Ce document décrit les normes de codage dans le langage de programmation Java chez Google. Le code source Java est considéré comme conforme à ces normes si, et seulement si, il répond à toutes les règles décrites dans ce document.



Les sujets abordés dans ce didacticiel ne concernent pas seulement l'aspect esthétique du formatage du code, mais également d'autres types de conventions ou de normes de codage. Cependant, ce document se concentre principalement sur la définition des règles strictes que nous suivons partout, et ne fournit pas de recommandations qui peuvent être mal implémentées (tant par l'homme que par les machines-outils).

1.1 Terminologie

Tout au long de ce guide, les termes suivants sont définis:

1. Le terme classe est utilisé pour désigner une classe, une énumération, une interface ou un type d'annotation "ordinaire" (@interface)
2. Le terme membre de classe est utilisé pour désigner une classe, un champ, une méthode ou un constructeur imbriqués, c'est-à-dire pour tous les membres de classe de haut niveau à l'exception des blocs d'initialisation et des commentaires.
3. Le terme commentaire fait toujours référence aux commentaires d'implémentation. Nous n'utilisons pas l'expression «commentaires de documentation», mais plutôt le terme «Javadoc»

Le reste de la terminologie sera fourni au besoin tout au long de ce manuel.

1.2 Note guide

Les exemples de code de ce document ne montrent pas la seule approche stylistique correcte de sa mise en forme, bien qu'ils soient utilisés dans notre didacticiel.

2. Fichier source. Les bases

2.1 Nom de fichier

Un nom de fichier source se compose du nom d'une classe de premier niveau spécifique qui y réside. Le nom est sensible à la casse et se termine par une extension .java

2.2 Encodage de fichier: UTF-8

Les fichiers avec code sont encodés en UTF-8.

2.3 Caractères spéciaux

2.3.1 Caractères d'espacement

Hormis la séquence de caractères de fin de ligne, le caractère d'espace ASCII horizontal (0x20) est le seul caractère de délimitation trouvé dans le fichier source. Cela signifie que:

1. Tous les autres caractères d'espacement dans les littéraux de caractère et de chaîne sont échappés
2. Les caractères de tabulation ne sont pas utilisés pour l'indentation

2.3.2 Séquences d'échappement spéciales

Pour chaque caractère pour lequel il existe une séquence d'échappement spéciale (\ b, \ t, \ n, \ f, \ r, \ ", \ 'et \\), il est préférable de l'utiliser à la place de sa valeur octale correspondante (par exemple, \ 012 ) ou du code Unicode (par exemple \ u000a).

2.3.3 Caractères non ASCII

Pour les caractères non ASCII, utilisez le caractère Unicode (par exemple, ∞) ou une séquence d'échappement équivalente (par exemple, \ u221e). Le choix est fait en faveur des symboles qui rendent le code plus compréhensible et lisible.

Lors de l'utilisation de caractères d'échappement Unicode et dans les cas où des caractères Unicode valides sont utilisés, nous recommandons fortement que ce code soit accompagné de commentaires explicatifs.

Ne rendez jamais votre code moins lisible par crainte que certains programmes ne soient pas en mesure de traiter correctement les caractères non ASCII. Si cela se produit, ces programmes ne fonctionnent pas correctement et doivent être corrigés.

3. Structure du fichier source

Le fichier source se compose des éléments suivants (dans l'ordre indiqué):

1. Informations sur la licence ou les droits d'auteur, le cas échéant
2. Déclaration de colis
3. Déclaration des importations
4. Déclaration de classe

Une seule ligne vierge sépare chaque section présente.

3.1 Informations sur la licence ou les droits d'auteur, le cas échéant

Les informations de licence ou de copyright doivent être incluses dans le fichier auquel elles se réfèrent.

3.2 Déclaration d'emballage

Le package est déclaré sans saut de ligne. La limitation de largeur de ligne (section 4.4) ne s'applique pas à une déclaration de package.

3.3 Déclarations d'importation

3.3.1 Caractère générique dans les déclarations d'importation

Le caractère * (joker) n'est pas utilisé lors de la déclaration d'importations, statiques ou non.

3.3.2 Saut de ligne

Les importations sont déclarées sans saut de ligne. Ils ne sont pas soumis à la limite de largeur de ligne.

3.3.3 Ordre et espacement

Les importations sont classées comme suit:

1. Toutes les importations statiques sont placées et regroupées dans un bloc
2. Toutes les importations non statiques sont placées dans un autre bloc

Si des importations statiques et non statiques sont déclarées, ces blocs doivent être séparés par une ligne vide. Il ne devrait y avoir aucune autre ligne vide entre eux.



Dans chaque bloc, les classes importées sont répertoriées dans l'ordre de tri des caractères ASCII.

3.3.4 Importation statique de classes imbriquées

Les importations statiques ne sont pas utilisées pour les classes imbriquées statiques. Ces classes sont importées avec une déclaration d'importation régulière.

3.4 Déclaration de classe

3.4.1 Une seule classe de premier niveau est déclarée

Chaque classe de niveau supérieur se trouve dans son propre fichier source.

3.4.2 Ordonner le contenu d'une classe

L'ordre dans lequel vous placez les membres et les blocs d'initialisation d'une classe peut avoir un impact important sur la facilité de compréhension de votre code. Quoi qu'il en soit, il n'y a pas de recette simple et correcte pour cela; différentes classes peuvent organiser leur contenu de différentes manières.



L'important est que chaque classe ait un ordre logique du contenu afin que le programmeur lisant le code puisse l'expliquer.

3.4.2.1 Le code surchargé ne doit pas être fractionné

Lorsqu'une classe a plusieurs constructeurs ou méthodes avec le même nom, ils doivent être placés séquentiellement sans insérer d'autre code entre les deux.

4. Formatage

Terminologie

Le corps d'une classe, d'une méthode ou d'un constructeur est une construction de bloc .



Notez que selon la section 4.8.3.1, tout initialiseur de tableau peut également être considéré comme une construction de bloc.

4.1 Bretelles frisées

4.1.1 Les accolades sont utilisées partout où elles peuvent être utilisées

Les accolades sont utilisées dans if, else, for, while et do-while, même si le corps de l'expression est vide ou ne contient qu'une seule ligne de code.

4.1.2 Blocs non vides: style K&R

Les accolades sont placées selon le style de Kernighan et Ritchie ("parenthèses égyptiennes") pour les blocs non vides et les structures de blocs (pour plus de clarté, nous avons décidé d'ajouter un petit code démontrant ces règles - note du traducteur):

• Aucun saut de ligne n'est effectué avant la parenthèse ouvrante:

// 
if (true) { 

// 
if (true)
{

• Un saut de ligne est effectué après la parenthèse ouvrante:

// 
while (true) {
  // code

// 
while (true) { // code

• Un saut de ligne est effectué avant la parenthèse fermante:

// 
for () {
  // code
}

// 
while (true) { /* code */ }

// 
if (true) {
  /* code */ }

• Un saut de ligne se produit après une parenthèse fermante uniquement si cette parenthèse termine une expression ou un corps d'une méthode, d'un constructeur ou d'une classe non anonyme. Un saut de ligne n'est pas fait après une parenthèse s'il est suivi d'un else, catch ou point-virgule

Exemples de règles correctement exécutées:

return () -> {
  while (condition()) {
    method();
  }
};

return new MyClass() {
  @Override public void method() {
    if (condition()) {
      try {
        something();
      } catch (ProblemException e) {
        recover();
      }
    } else if (otherCondition()) {
      somethingElse();
    } else {
      lastThing();
    }
  }
};

Certaines exceptions pour les énumérations sont données à la section 4.8.1

4.1.3 Les blocs vides peuvent être compressés

Un bloc vide ou une construction de bloc vide peut suivre le style K & R (comme décrit dans la section 4.1.2). Il est également possible qu'un tel bloc soit fermé immédiatement après l'ouverture, sans caractère ni saut de ligne à l'intérieur de {}. Cette règle ne s'applique pas lorsque le bloc fait partie d'une expression multi-bloc qui contient un if-else ou try-catch-finally.



Exemples:

// 
void doNothing() {}

//  
void doNothingElse() {
}

// :       
try {
  doSomething();
} catch (Exception e) {}

4.2 Deux espaces pour l'indentation

Chaque fois qu'un nouveau bloc ou une nouvelle structure de bloc est ouvert, le décalage vers la droite est augmenté de deux espaces. Lorsqu'un bloc se termine, le début de la ligne de code suivante est décalé vers le niveau de décalage précédent. Le niveau de décalage s'applique à la fois au bloc et aux commentaires de ce bloc (voir un exemple dans la section 4.1.2).

4.3 Une expression par ligne

Chaque expression se termine par un saut de ligne.

4.4 Limitation de la largeur de ligne à 100 caractères

Le code Java est limité à 100 caractères en largeur de ligne. Un «caractère» fait référence à l'un des éléments Unicode. Sauf comme décrit ci-dessous, chaque ligne dépassant la limite de largeur doit être enveloppée comme expliqué dans la section 4.5.



Des exceptions:

1. , (, URL Javadoc JSNI- )
2. package import (. 3.2 3.3)
3. ,

4.5

Lorsque du code qui pourrait autrement être sur la même ligne est divisé sur plusieurs lignes, ce phénomène est appelé saut de ligne.



Il n'y a pas de formule non ambiguë généralement acceptée qui détermine exactement comment les sauts de ligne doivent être effectués dans chaque situation. Très souvent, il existe plusieurs façons de rompre une ligne avec le même morceau de code.



Habituellement, l'enroulement est effectué pour éviter un dépassement de largeur de ligne. Mais même si le code restait dans la largeur autorisée, alors, à la décision de l'auteur, il peut être encapsulé dans une nouvelle ligne.

L'allocation d'une méthode d'assistance ou d'une variable locale peut résoudre le problème de dépassement de largeur de ligne sans envelopper le code

4.5.1 Où transférer

Le premier guide pour les sauts de ligne dit: il est préférable de faire le saut de ligne à un niveau syntaxique plus élevé. Aussi:



1. Lorsqu'une ligne est interrompue sur une instruction de non-affectation, la coupure est faite avant le caractère.



Cette règle s'applique également aux caractères "de type opérateur" suivants:

• point de division "."
• double-virgule de la méthode de référence "::"
• esperluette entre parenthèses générique <T étend Foo & Bar>
• délimiteur dans le bloc catch (FooException | BarException e)

2. Lorsqu'une chaîne est encapsulée dans une instruction d'affectation, l'enroulement est généralement effectué après le caractère, mais une autre solution



est acceptable. Cela s'applique également aux deux points de la boucle for-each.



3. Le nom de la méthode ou du constructeur lorsque les sauts de ligne restent attachés à la parenthèse ouvrante "("



4. La virgule "," lorsque les sauts de ligne restent avec l'élément qui le précède



5. La ligne n'est jamais encapsulée directement à la flèche de l'expression lambda, sauf si son corps est constitué d'une seule expression sans accolades:

MyLambda<String, Long, Object> lambda =
    (String label, Long value, Object obj) -> {
        ...
    };

Predicate<String> predicate = str ->
    longExpressionInvolving(str);

Le but principal des sauts de ligne est de clarifier le code, mais pas nécessairement le plus petit nombre de lignes

4.5.2 Décaler la continuation de la ligne de 4 espaces ou plus

Lorsqu'une ligne saute, chaque sous-chaîne suivante (chaque continuation de ligne) est décalée d'au moins 4 espaces par rapport à la précédente.



Lorsqu'il y a plusieurs suites de lignes, le décalage peut varier dans les 4 espaces à la demande de l'auteur. En règle générale, deux extensions de ligne peuvent avoir le même décalage si et seulement si elles commencent par des éléments syntaxiquement parallèles.



La section 4.6.3 fournit des conseils sur l'utilisation de quantités variables d'espaces blancs pour aligner les points de code par rapport aux lignes précédentes.

4.6 Espaces et retraits

4.6.1 Indentation

Une ligne vide est toujours placée:



1. Entre les membres successifs ou les initialiseurs de classe: champs, constructeurs, méthodes, classes imbriquées, blocs d'initialisation statiques et dynamiques

• exception: une ligne vide entre deux champs consécutifs (aucun code entre eux) est facultative. Les lignes vides sont utilisées pour regrouper les champs de manière logique si nécessaire
• exception: lignes vides entre les constantes de classe enum (voir Section 4.8.1)

2. Conforme à d'autres sections de ce document (par exemple, section 3 et section 3.3) La



ligne vide peut également être utilisée partout pour améliorer la lisibilité du code, par exemple entre les expressions pour organiser le code en sous-sections logiques. Une chaîne vide avant le premier membre d'une classe, ou un bloc d'initialisation, ou après le dernier membre, ou un bloc d'initialisation d'une classe est déconseillée, mais pas interdite.



Plusieurs lignes vierges consécutives sont autorisées, mais pas nécessaires ni encouragées.

4.6.2 Espaces

Outre les exigences de la langue elle-même ou d'autres règles de ce document, ainsi que sans compter les littéraux et les commentaires (y compris Javadoc), les espaces simples de la table ASCII ne peuvent être présents qu'aux endroits suivants:



1. Lors de la séparation d'un mot réservé tel que si, for or catch et une parenthèse ouvrante "(" qui suit



2. Lors de la séparation d'un mot réservé, comme else ou catch, et une accolade fermante "}" qui suit



3. Avant toute accolade ouvrante " {", Sauf dans deux cas:

• @SomeAnnotation ({a, b})
• String [] [] x = {{"toto"}}; - espace entre {{non requis selon la clause 8 ci-dessous

4. De part et d'autre de tout opérateur binaire ou ternaire



Cette règle s'applique également aux opérateurs suivants:

• esperluette entre crochets angulaires: <T étend Foo & Bar>
• un délimiteur dans un bloc catch contenant plusieurs exceptions: catch (FooException | BarException e)
• deux points ":" in for-each
• flèche dans l'expression lambda: (String str) -> str.length ()

Mais cette règle ne s'applique pas aux opérateurs:

• deux points "::" de la méthode de référence, qui s'écrit Object :: toString
• le point de séparation ".", qui s'écrit object.toString ()

5. Après ",:;" ou la parenthèse fermante ")" lors de la conversion en type



6. De chaque côté de la double barre oblique "//" lors de la création d'un commentaire sur la même ligne de code. Plusieurs espaces sont autorisés mais pas obligatoires ici



7. Entre la déclaration de type et le nom de la variable:

List<String> list

8. Facultatif: à l'intérieur des parenthèses de l'initialiseur de tableau,

new int [] {5, 6} et new int [] {5, 6} sont tous les deux valides



9. Entre l'annotation de type et [] ou ...



Cette règle ne nécessite pas la présence ou l'absence d'espaces dans début ou fin d'une ligne; il ne s'applique qu'aux espaces internes.

4.6.3 L'alignement horizontal n'est jamais nécessaire

Terminologie

L'alignement horizontal consiste à ajouter un nombre variable d'espaces supplémentaires dans votre code pour faire apparaître certains éléments sous d'autres éléments de la ligne précédente.



Cette pratique est autorisée mais n'est pas requise par ce guide. Il n'est pas non plus nécessaire de maintenir l'alignement dans les parties du code où il a déjà été appliqué.



Exemple avec et sans alignement:

private int x; // 
private Color color; //   

private int   x;      // ,     
private Color color;  //    

L'alignement améliore la lisibilité du code, mais crée des problèmes avec la maintenance de ce code à l'avenir. Disons que vous ne souhaitez modifier qu'une seule ligne. Cette modification peut corrompre le formatage du code précédemment accepté, ce qui est acceptable. Mais, très probablement, le programmeur (peut-être vous) commencera à ajuster le nombre d'espaces sur les lignes adjacentes, ce qui déclenchera peut-être toute une série de corrections. Changer une ligne peut déclencher une «vague explosive» de travail insensé (au pire). Ou, au mieux, cela déformera les informations de l'historique des versions, altérera la lisibilité du code et exacerbera les conflits de fusion.

4.7 Il est recommandé de regrouper les crochets

Vous ne devez omettre les parenthèses de regroupement que si l'auteur du code et le réviseur conviennent qu'il n'y a aucune probabilité raisonnable que le code soit mal interprété sans parenthèses, et les parenthèses ne faciliteraient pas la lecture. Il n'y a aucune raison de croire que quiconque lit le code a mémorisé l'intégralité de la table de priorité des opérateurs Java.

4.8 Modèles spéciaux

4.8.1 Classes d'énumération

Après chaque virgule qui suit une constante d'énumération, un saut de ligne est facultatif. Les lignes vierges supplémentaires (généralement une seule) sont également autorisées. Voici un exemple d'un tel code:

private enum Answer {
  YES {
    @Override public String toString() {
      return "yes";
    }
  },

  NO,
  MAYBE
}

Le code d'une classe d'énumération sans méthodes ni commentaires décrivant ses constantes peut être représenté comme un initialiseur de tableau (voir Section 4.8.3.1):

private enum Suit { CLUBS, HEARTS, SPADES, DIAMONDS }

Puisque les énumérations sont des classes, toutes les autres règles qui s'appliquent aux classes doivent s'y appliquer.

4.8.2 Déclarations de variables

4.8.2.1 Une variable par déclaration

Chaque variable (field ou locale) est déclarée une seule à la fois: des déclarations telles que int a, b; ne sont pas utilisés.



Exception : plusieurs déclarations de variables sont autorisées dans l'en-tête d'une boucle for.

4.8.2.2 Déclarer des variables lorsque vous en avez besoin

Les variables locales n'ont pas besoin d'être déclarées au début d'une construction de bloc ou de bloc. Inversement, les variables locales doivent être déclarées juste avant leur première utilisation pour minimiser leur portée. Habituellement, les variables locales sont initialisées au moment de la déclaration, ou immédiatement après.

4.8.3 Tableaux

4.8.3.1 Les initialiseurs de tableau peuvent être "bloc"

Tout tableau peut être initialisé comme s'il s'agissait d'une construction de bloc. Par exemple, tout le code suivant est valide (la liste des exemples n'est pas complète):

new int[] {
  0, 1, 2, 3
}
                        
new int[] {
  0, 1,
  2, 3
}

new int[]
    {0, 1, 2, 3}

new int[] {
  0,
  1,
  2,
  3
}

4.8.3.2 Aucune déclaration de tableau de style C

Les crochets sont placés après le type, pas après la variable: String [] args, pas String args [].

4.8.4 L'instruction switch

Terminologie

Un ou plusieurs groupes d'instructions sont situés dans un bloc de commutation. Chaque groupe est constitué d'une ou plusieurs étiquettes (les deux cas FOO: et par défaut :) suivis d'une ou plusieurs instructions (ou, dans le cas du dernier groupe, aucune ou plus).

4.8.4.1 Décalage

Comme pour tout autre bloc, le contenu du bloc de commutation est décalé de 2 espaces.



Un saut de ligne est effectué après le libellé du bloc de commutation et le décalage est augmenté de 2 espaces, comme à l'ouverture du bloc. Chaque étiquette suivante revient au niveau de décalage précédent, comme lors de la fermeture d'un bloc.

4.8.4.2 La transmission est commentée

Dans un bloc, chaque groupe d'instructions se termine avant la planification avec un commutateur (en utilisant break, continue, return ou lançant une exception), ou est marqué d'un commentaire pour indiquer que l'exécution du code se poursuivra ou pourra continuer dans le groupe suivant. Tout commentaire véhiculant l'idée d'un passage traversant (généralement // échouer) est suffisant. Ce commentaire n'est pas obligatoire dans le dernier groupe du bloc de commutation. Exemple:

switch (input) {
  case 1:
  case 2:
    prepareOneOrTwo();
    // fall through
  case 3:
    handleOneTwoOrThree();
    break;
  default:
    handleLargeNumber(input);
}

Veuillez noter que le commentaire n'est pas placé après le cas 1, mais uniquement à la fin du groupe d'instructions.

4.8.4.3 Toujours utiliser la valeur par défaut

L'instruction switch doit contenir l'étiquette par défaut, même si elle ne contient aucun code.



Exception : un bloc de commutation pour un type enum ne peut pas utiliser default s'il contient des cas explicites couvrant toutes les valeurs possibles de ce type. Cela permet à l'EDI ou à d'autres outils d'analyse statique d'émettre un avertissement indiquant que certains cas ne sont pas couverts.

4.8.5 Annotations

Les annotations appliquées à une classe, une méthode ou un constructeur suivent immédiatement le bloc doc. Chaque annotation est répertoriée sur sa propre ligne (c'est-à-dire une annotation par ligne). Ces sauts de ligne ne sont pas des sauts de ligne (voir Section 4.5), donc le niveau d'indentation n'est pas augmenté. Exemple:

@Override
@Nullable
public String getNameIfPresent() { ... }

Exception : une seule annotation sans paramètres peut être affichée avec la première ligne de signature, par exemple:

@Override public int hashCode() { ... }

Les annotations appliquées à un champ apparaissent également immédiatement après le bloc doc, mais dans ce cas, plusieurs annotations (éventuellement paramétrées) peuvent être répertoriées sur une seule ligne, par exemple:

@Partial @Mock DataLoader loader;

Il n'y a pas de règles spéciales pour le formatage des annotations pour les paramètres, les variables locales ou les types.

4.8.6 Commentaires

Cette section est dédiée aux commentaires d'implémentation. Javadoc est traité séparément dans la section 7.



Tout saut de ligne peut être précédé d'un nombre arbitraire d'espaces, suivi d'un commentaire d'implémentation. Ce commentaire rend la ligne non vide.

4.8.6.1 Style de commentaire de bloc

Le niveau d'indentation d'un commentaire de bloc est le même que le code environnant. Les commentaires de bloc peuvent être soit / *… * / soit //… Pour les commentaires sur plusieurs lignes comme / *… * /, les lignes suivantes doivent commencer par un *, aligné avec un * de la ligne précédente.

/*
 * This is          // And so           /* Or you can
 * okay.            // is this.          * even do this. */
 */

Les commentaires ne sont pas entourés de rectangles représentés par des astérisques ou d'autres symboles.

Lorsque vous écrivez des commentaires sur plusieurs lignes, utilisez le style / * ... * / si vous voulez que le formateur de code automatique coupe la ligne si nécessaire (dans le style des paragraphes). La plupart des formateurs ne peuvent pas faire cela avec des blocs de commentaires sur une seule ligne // ...

4.8.7 Modificateurs

Les modificateurs de classe et de champ, s'ils sont présents, sont affichés dans l'ordre recommandé par la spécification du langage Java:

public protected private abstract default static final transient volatile synchronized native strictfp

4.8.8 Littéraux numériques

Le type long utilise un L majuscule, pas une lettre minuscule (pour ne pas être confondu avec le chiffre 1). Par exemple, 300_000_000L au lieu de 300_000_000l.

5. Dénomination

5.1 Règles générales pour tous les identifiants

Les identificateurs utilisent uniquement des lettres et des chiffres ASCII et, dans certains cas indiqués ci-dessous, des traits de soulignement.



Ainsi, chaque nom d'identifiant valide correspond à l'expression régulière \ w + (un caractère alphanumérique qui apparaît une ou plusieurs fois).



Les noms qui utilisent des suffixes ou des préfixes spéciaux, tels que name_, mName, s_name ou kName, ne sont pas conformes au style de ce didacticiel.

5.2 Règles pour différents types d'identifiants

5.2.1 Noms des packages

Les noms de packages doivent être écrits en minuscules, sans camelCase ni tirets bas.



Correct: com.example.deepspace

Incorrect: com.example.deepSpace ou com.example.deep_space

5.2.2 Noms de classe

Les noms de classe sont écrits dans le style UpperCamelCase (première lettre en majuscule).



Les noms de classe sont généralement des noms ou des phrases nominales. Par exemple, Character ou ImmutableList.



Les noms d'interface peuvent également être des noms ou des expressions nominales (par exemple, Liste), mais parfois ils peuvent également être des adjectifs ou des combinaisons d'adjectifs (par exemple, Lisible).



Il n'y a pas de règles spécifiques ou même de conventions bien établies pour nommer les types d'annotations.



Les classes de test ont un nom qui commence par le nom de la classe qu'elles testent et se termine par Test. Par exemple, HashTest ou HashIntegrationTest.

5.2.3 Noms des méthodes

Les noms de méthode sont écrits dans le style lowerCamelCase.



Les noms de méthode sont généralement des verbes ou des phrases verbales. Par exemple sendMessage ou stop.



Les traits de soulignement peuvent être utilisés dans les noms de méthode de test JUnit pour séparer les composants logiques du nom. De plus, chaque composant est écrit dans le style lowerCamelCase. Le modèle typique est:

<methodUnderTest>_<state>, , pop_emptyStack

Il n'y a pas de manière correcte de nommer les méthodes de test.

5.2.4 Noms de constantes

Les constantes sont nommées dans le style CONSTANT_CASE: toutes les lettres sont en majuscules, chaque mot séparé du suivant par un trait de soulignement. Mais qu'est-ce qu'une constante exactement?



Les constantes sont des champs finaux statiques dont le contenu est immuable et des méthodes qui n'ont aucun effet secondaire visible. Cela s'applique aux primitives, aux chaînes, aux types immuables et aux collections immuables de types immuables. Si un état observable d'un objet peut changer, ce n'est pas une constante. Une simple intention de ne jamais modifier un objet ne suffit pas.



Exemples:

// 
static final int NUMBER = 5;
static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann");
static final ImmutableMap<String, Integer> AGES = ImmutableMap.of("Ed", 35, "Ann", 32);
static final Joiner COMMA_JOINER = Joiner.on(','); // because Joiner is immutable
static final SomeMutableType[] EMPTY_ARRAY = {};
enum SomeEnum { ENUM_CONSTANT }

//  
static String nonFinal = "non-final";
final String nonStatic = "non-static";
static final Set<String> mutableCollection = new HashSet<String>();
static final ImmutableSet<SomeMutableType> mutableElements = ImmutableSet.of(mutable);
static final ImmutableMap<String, SomeMutableType> mutableValues =
    ImmutableMap.of("Ed", mutableInstance, "Ann", mutableInstance2);
static final Logger logger = Logger.getLogger(MyClass.getName());
static final String[] nonEmptyArray = {"these", "can", "change"};

Les noms constants sont généralement des noms ou des phrases nominales.

5.2.5 Noms des champs non constants

Les noms des champs qui ne sont pas des constantes (statiques ou non) sont écrits dans le style lowerCamelCase.



Les noms de ces champs sont généralement des noms ou des phrases nominales. Par exemple, computedValues ​​ou index.

5.2.6 Noms des paramètres

Les noms de paramètres sont écrits dans le style lowerCamelCase.



Les noms de paramètres à un caractère doivent être évités dans les méthodes publiques.

5.2.7 Noms des variables locales

Les noms des variables locales sont écrits dans le style lowerCamelCase.



Même si elles sont définitives et immuables, les variables locales ne sont pas considérées comme des constantes et ne doivent pas être écrites dans le même style que les constantes.

5.2.8 Noms des variables de type

Chaque variable de type est nommée selon l'un des deux styles:

• Lettre majuscule unique, qui peut être suivie d'un nombre régulier (par exemple, E, T, X, T2)
• Un nom sous la forme d'un nom de classe (voir Section 5.2.2) suivi d'une lettre T majuscule (exemples: RequestT, FooBarT).

5.3 CamelCase

Parfois, il existe plusieurs façons de convertir une phrase anglaise en style camel, comme dans le cas d'abréviations ou d'expressions atypiques comme «IPv6» ou «iOS».



Pour améliorer la prévisibilité, ce guide présente le schéma (exemplaire) suivant.



En commençant par la forme originale du nom:



1. Convertissez la phrase en ASCII normal et supprimez toutes les apostrophes. Par exemple, "l'algorithme de Müller" peut être converti en "algorithme de Muellers"



2. Divisez le résultat en mots, en supprimant les espaces et toute ponctuation restante (généralement des traits d'union):

• recommandation: si un mot a déjà une forme commune dans le style «chameau» habituel, divisez-le en ses composants (par exemple, «AdWords» est converti en «mots publicitaires»). Notez qu'un mot comme «iOS» n'est pas vraiment à la camel; elle n'est conforme à aucune convention, donc cette recommandation ne s'applique pas.

3. Convertissez maintenant tout en minuscules (y compris les abréviations), puis convertissez en majuscules le premier caractère:

• ... dans chaque mot pour obtenir le style UpperCamelCase, ou
• ... dans chaque mot sauf le premier pour obtenir le style lowerCamelCase

4. Enfin, concaténez tous les mots en un seul identifiant.



Notez que la casse des mots originaux est presque complètement ignorée.



Exemples:



* Autorisé mais non recommandé.



Remarque : certains mots en anglais utilisent un trait d'union de manière ambiguë: par exemple, «nonempty» et «non-empty» sont corrects, donc les noms de méthode checkNonempty et checkNonEmpty sont également corrects.

6. Pratique de la programmation

6.1 Toujours utiliser l'annotation @Override

La méthode est annotée avec l'annotation @Override chaque fois qu'elle est réellement remplacée. Cela s'applique à la fois à une méthode d'une classe descendante qui remplace une méthode d'une classe parent et à une méthode d'interface qui remplace une méthode d'une super-interface.



Exception : l'annotation peut être omise si la méthode parente est marquée avec l'annotation @Deprecated.

6.2 N'ignorez pas les exceptions interceptées

Il est très rare qu'il y ait des situations où vous n'avez pas besoin de prendre d'action en réponse à une exception interceptée (une solution typique est de la consigner ou, si cela est considéré comme "impossible", de lever l'exception en tant qu'assertionError).



Voici un exemple avec un commentaire explicatif sur le moment où il est vraiment approprié de ne prendre aucune action dans le bloc catch:

try {
  int i = Integer.parseInt(response);
  return handleNumericResponse(i);
} catch (NumberFormatException ok) {
  // it's not numeric; that's fine, just continue
}
return handleTextResponse(response);

Exception : dans les tests, une exception interceptée peut être ignorée et annulée si le nom du test est attendu ou si le nom commence par attendu. Ce qui suit est un idiome très courant montrant que le code testé lève une exception du type attendu, donc aucun commentaire n'est nécessaire ici:

try {
  emptyStack.pop();
  fail();
} catch (NoSuchElementException expected) {
}

6.3 Pour les membres statiques, utilisez le nom de la classe

Il est nécessaire d'accéder à un membre d'une classe statique via le nom de la classe, et non par référence à un objet de classe ou par une expression qui renvoie cet objet:

Foo aFoo = ...;
Foo.aStaticMethod(); // 
aFoo.aStaticMethod(); // 
somethingThatYieldsAFoo().aStaticMethod(); //  

6.4 N'utilisez pas de finaliseurs

Il est extrêmement rare que vous deviez remplacer la méthode Object.finalize.



Indice :



ne faites pas ça. Si vous en avez vraiment besoin, lisez d'abord et comprenez bien l'élément 7 de Java efficace, Évitez les finaliseurs, puis ne le faites pas.

7. Javadoc

7.1 Formatage

7.1.1 Forme principale

Le formatage simple des blocs Javadoc suit cet exemple:

/**
 * Multiple lines of Javadoc text are written here,
 * wrapped normally...
 */
public int method(String p1) { ... }

... ou sur une ligne:

/** An especially short bit of Javadoc. */

Le formulaire simple est toujours applicable. Le formulaire en une ligne peut être appliqué lorsque le bloc Javadoc entier (y compris les marqueurs de commentaire) peut tenir sur une seule ligne. Notez que cela ne s'applique que lorsqu'il n'y a pas de balises telles que @return dans le bloc.

7.1.2 Paragraphes

Une ligne vide, c'est-à-dire une ligne contenant uniquement un astérisque de tête aligné (*), apparaît entre les paragraphes et avant le groupe de balises de bloc, le cas échéant. Chaque paragraphe à l'exception du premier contient un <p> immédiatement avant le premier mot, sans espace après.

7.1.3 Balises de bloc

Toutes les balises de bloc sont dans cet ordre: @param, @return, @throws, @deprecated, et ces quatre types ne sont jamais présents avec des descriptions vides. Si une balise de bloc ne tient pas sur une ligne, les lignes de continuation sont indentées de quatre (ou plus) espaces à partir de @.

7.2 Extrait final

Chaque bloc Javadoc commence par un court extrait de résumé. Cet extrait est très important: c'est le seul texte qui apparaît dans un contexte spécifique, comme les index de classe et de méthode.



Cet extrait de code est un nom ou une phrase verbale, pas une phrase complète. Il ne commence pas par A {@code Foo} est un ... ou Cette méthode retourne ..., ni ne forme une phrase affirmative complète comme Enregistrer l'enregistrement. Cependant, ce passage est mis en majuscule et ponctué comme s'il s'agissait d'une phrase complète.



Astuce : C'est une erreur courante d'écrire un simple Javadoc comme / ** @return l'ID client * /. Ceci est incorrect et doit être corrigé en / ** Renvoie l'ID client. * /.

7.3 Quand Javadoc est appliqué

Javadoc est présent dans au moins chaque classe publique et chaque membre public et protégé de cette classe, sauf dans certains cas, décrits ci-dessous.

Un Javadoc supplémentaire peut être présent, comme expliqué dans Section 7.3.4, Javadoc facultatif.

7.3.1 Exception: méthodes qui se décrivent

Javadoc est facultatif pour les méthodes simples et évidentes comme getFoo dans les cas où vous ne pouvez vraiment pas en dire plus que "Renvoie foo".



Important : il est inapproprié de se référer à cette exception pour justifier l'omission d'informations pertinentes dont le lecteur général pourrait avoir besoin.



Par exemple, pour une méthode nommée getCanonicalName, n'omettez pas la documentation (avec la justification que le nom de la méthode dit seulement / ** Renvoie le nom canonique. * /) Si la personne moyenne lisant le code peut même ne pas soupçonner ce que signifie le terme «nom canonique» !

7.3.2 Exception: priorité

Javadoc n'accompagne pas toujours une méthode qui remplace une méthode d'une super classe (ou super interface).

7.3.4 Javadoc en option

Les autres classes et membres sont accompagnés par Javadoc selon les besoins ou souhaités.



Chaque fois qu'un commentaire d'implémentation sera utilisé pour définir l'objectif général ou le comportement d'une classe ou d'un membre, ce commentaire est écrit sous la forme Javadoc (en utilisant / **).



Le Javadoc optionnel n'a pas à suivre les règles de formatage des sections 7.1.2, 7.1.3 et 7.2, bien que cela soit bien sûr recommandé.



Cette traduction est également disponible sur notre blog.