1Introduction

Ce document sert de définition complète des normes de codage de Google pour le code source dans le langage de programmation Java™. Un fichier source Java est décrit comme étant de style inGoogle si et seulement s’il respecte les règles ci-dessous.

Comme d’autres guides de style de programmation, les questions abordées couvrent non seulement des problèmes esthétiques de formatage, mais également d’autres types de conventions ou de normes de codage. Cependant, ce document se concentre principalement sur les règles strictes que nous suivons universellement, et évite de donner des conseils qui ne sont pas clairement applicables (que ce soit par un humain ou un outil).

1.1 Notes terminologiques

Dans ce document, sauf indication contraire :

1. Le terme classe est utilisé inclusivement pour désigner une classe « ordinaire », une classe enum, une interface ou un type d’annotation (@interface).
2. Le terme membre (d’une classe) est utilisé inclusivement pour désigner une classe, un champ, une méthode ou un constructeur imbriqués; c’est-à-dire tous les contenus de niveau supérieur d’une classe à l’exception des initialiseurs 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 commun « Javadoc. »

D’autres  » notes terminologiques  » apparaîtront occasionnellement tout au long du document.

1.2 Notes de guide

L’exemple de code dans ce document n’est pas normatif. Autrement dit, alors que les exemples sont dans le style de Google, ils peuvent ne pas illustrer la seule façon élégante de représenter le code. Les choix de formatage optionnels effectués dans les exemples ne doivent pas être appliqués en tant que règles.

2 Bases du fichier source

2.1 Nom du fichier

Le nom du fichier source se compose du nom sensible à la casse de la classe de niveau supérieur qu’il contient (dont il existe exactement une), plus l’extension .java.

2.2 Encodage des fichiers: UTF-8

Les fichiers sources sont encodés en UTF-8.

2.3 Caractères spéciaux

2.3.1 Caractères d’espace

Mis à part la séquence de terminaison de ligne, le caractère d’espace horizontal ASCII (0x20) est le seul caractère d’espace qui apparaît partout dans un fichier source. Cela implique que:

1. All other whitespace characters in string and character literals are escaped.
2. Tab characters are not used for indentation.

2.3.2 Special escape sequences

For any character that has a special escape sequence(\b\t\n\f\r\"\' and\\), that sequenceis used rather than the corresponding octal(e.g. \012) or Unicode(e.g. \u000a) s’échapper.

2.3.3 Caractères non ASCII

Pour les caractères non ASCII restants, soit le caractère Unicode réel (par exemple ∞), soit l’échappement Unicode équivalent (par exemple \u221e) est utilisé. Le choix ne dépend que dece qui rend le code plus facile à lire et à comprendre, bien que les littéraux et les commentaires de chaînes hors-chaîne Unicode soient fortement déconseillés.

Astuce: Dans le cas d’échappement Unicode, et parfois même lorsque des caractères actualUnicode sont utilisés, un commentaire explicatif peut être très utile.

Exemples:

Exemple	Discussion
String unitAbbrev = "μs";	Meilleur: parfaitement clair même sans commentaire.
String unitAbbrev = "\u03bcs"; // "μs"	Autorisé, mais il n’y a aucune raison de le faire.
String unitAbbrev = "\u03bcs"; // Greek letter mu, "s"	Autorisé, mais gênant et sujet aux erreurs.
String unitAbbrev = "\u03bcs";	Pauvre: le lecteur n’a aucune idée de ce que c’est.
return '\ufeff' + content; // byte order mark	Bon: utilisez des échappements pour les caractères non imprimables, et commentez si nécessaire.

Astuce: Ne rendez jamais votre code moins lisible simplement de peur que certains programmes ne gèrent pas correctement les caractères non-ASCII. Si cela devait arriver, ceuxles programmes sont cassés et ils doivent être réparés.

3 Structure du fichier source

Exactement une ligne vide sépare chaque section présente.

3.1 Informations sur la licence ou les droits d’auteur, si elles sont présentes

Si les informations sur la licence ou les droits d’auteur appartiennent à un fichier, elles appartiennent ici.

3.2 Instruction Package

L’instruction package n’est pas encapsulée en ligne. La limite de colonne (section 4.4, Limite de colonne : 100) ne s’applique pas aux instructions de paquet.

3.3 Instructions d’importation

3.3.1 Aucune importation de caractères génériques

Les importations de caractères génériques, statiques ou autres, ne sont pas utilisées.

3.3.2 Aucun enveloppement de ligne

Les instructions d’importation ne sont pas enveloppées de ligne. La limite de colonne (Section 4.4, Limite de colonne : 100) ne s’applique pas aux déclarations d’importation.

3.3.3 Ordonnancement et espacement

Les importations sont ordonnées comme suit :

1. Toutes les importations statiques dans un seul bloc.
2. Toutes les importations non statiques dans un seul bloc.

S’il y a des importations statiques et non statiques, une seule ligne vide sépare les deux blocs. Il n’y a pas d’autres lignes vides entre les instructions d’importation.

Dans chaque bloc, les noms importés apparaissent dans l’ordre de tri ASCII. (Remarque : ce n’est pas la même chose que les instructions d’importation étant dans l’ordre de tri ASCII, puisque ‘.’trie avant’; ‘.)

3.3.4 Aucune importation statique pour les classes

L’importation statique n’est pas utilisée pour les classes imbriquées statiques. Ils sont importés avecimports normales.

3.4 Déclaration de classe

3.4.1 Exactement une déclaration de classe de niveau supérieur

Chaque classe de niveau supérieur réside dans un fichier source qui lui est propre.

3.4.2 Ordre du contenu de la classe

L’ordre que vous choisissez pour les membres et les initialiseurs de votre classe peut avoir un grand effet surl’apprentissage. Cependant, il n’y a pas de recette correcte unique pour le faire; différentes classes peuvent ordonner leur contenu de différentes manières.

Ce qui est important, c’est que chaque classe utilise un ordre logique, que itsmaintainer pourrait expliquer si on le lui demandait. Par exemple, les nouvelles méthodes ne sont pas simplement ajoutées habituellement à la fin de la classe, car cela donnerait un ordre « chronologique par date d’ajout », ce qui n’est pas un ordre logique.

3.4.2.1 Surcharges: ne jamais diviser

Lorsqu’une classe a plusieurs constructeurs, ou plusieurs méthodes avec le même nom, ceux-ci apparaissent de manière séquentielle, sans autre code entre les deux (pas même les membres privés).

4 Formatage

Note terminologique : la construction de type bloc fait référence au corps d’une classe, d’une méthode ou d’un constructeur. Notez que, selon la section 4.8.3.1 sur les initialiseurs de tableau, tout initialiseur de tableau peut éventuellement être traité comme s’il s’agissait d’une construction de type bloc.

4.1 Accolades

4.1.1 Les accolades sont utilisées lorsque des accolades facultatives

sont utilisées avec ifelsefordo et while instructions, même lorsque le corps est vide ou ne contient qu’une seule instruction.

4.1.2 Blocs non vides : K &Style R

Les accolades suivent le style Kernighan et Ritchie (« parenthèses égyptiennes ») pour les blocs non vides et les constructions de type bloc :

• Pas de saut de ligne avant l’accolade d’ouverture.
• Saut de ligne après l’accolade d’ouverture.
• Saut de ligne avant l’accolade de fermeture.
• Saut de ligne après l’accolade de fermeture, uniquement si cette accolade termine une instruction ou termine le corps d’une méthode, d’un constructeur ou d’une classe nommée. Par exemple, il n’y a pas de saut de ligne après l’accolade si elle est suivie de else ou d’une virgule.

Exemples :

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(); } }};

Quelques exceptions pour les classes enum sont données dans la section 4.8.1, Classes Enum.

4.1.3 Blocs vides: peut être concis

Un bloc vide ou une construction de type bloc peut être de style K & R (comme décrit dans la section 4.1.2). Alternativement, il peut être fermé immédiatement après son ouverture, sans caractères ni saut de ligne entre les deux ({}), sauf s’il fait partie de l’instruction amulti-block (celle qui contient directement plusieurs blocs : if/else ou try/catch/finally).

Exemples :

 // This is acceptable void doNothing() {} // This is equally acceptable void doNothingElse() { }

 // This is not acceptable: No concise empty blocks in a multi-block statement try { doSomething(); } catch (Exception e) {}

4.2 Indentation de bloc: +2 espaces

Chaque fois qu’un nouveau bloc ou une construction de type bloc est ouvert, le retrait augmente de deux espaces. Lorsque le bloc se termine, le retrait revient au niveau de retrait précédent. Le niveau d’indentation s’applique à la fois au code et aux commentaires tout au long du bloc. (Voir l’exemple dans la section 4.1.2, Blocs non vides : K & Style R.)

4.3Une instruction par ligne

Chaque instruction est suivie d’un saut de ligne.

4.4 Limite de colonne: 100

Le code Java a une limite de colonne de 100 caractères. Un « caractère » désigne tout point de code Unicode.À l’exception de ce qui est indiqué ci-dessous, toute ligne qui dépasserait cette limite doit être enroulée, comme expliqué à la section 4.5, Enveloppement de ligne.

Chaque point de code Unicode compte comme un caractère, même si sa largeur d’affichage est plus grande ou moins grande. Par exemple, si vous utilisez des caractères à pleine largeur, vous pouvez choisir d’envelopper la ligne plus tôt que lorsque cette règle l’exige strictement.

Exceptions :

1. Lignes où il n’est pas possible d’obéir à la limite de colonne (par exemple, une URL longue dans Javadoc ou une référence de méthode JSNI longue).les instructions
2. package et import (voir les sections 3.2 Instruction Package et 3.3 instruction Import).
3. Lignes de commande dans un commentaire qui peut être coupé-collé dans un shell.

4.5 Line-wrapping

Note terminologique : Lorsque le code qui pourrait autrement occuper légalement une seule ligne est divisé en plusieurs lignes, cette activité est appelée line-wrapping.

Il n’existe pas de formule déterministe complète montrant exactement comment aligner chaque situation. Très souvent, il existe plusieurs façons valables d’envelopper le même morceau de code.

Remarque: Bien que la raison typique de l’encapsulation de lignes soit d’éviter de déborder la limite de colonne, même le code qui correspondrait en fait à la limite de colonne peut être encapsulé à la discrétion de l’auteur.

Astuce: L’extraction d’une méthode ou d’une variable locale peut résoudre le problème sans avoir besoin d’envelopper la ligne.

4.5.1 Où casser

La directive principale de l’enroulement de ligne est la suivante: préférez casser à un niveau syntaxique plus élevé. Aussi :

1. Lorsqu’une ligne est cassée chez un opérateur non-affectation, la rupture vient avant le symbole. (Notez que ce n’est pas la même pratique utilisée dans le style Google pour d’autres langages, tels que C ++ et JavaScript.)
   • Ceci s’applique également aux symboles « de type opérateur » suivants :
     • le séparateur de points (.)
     • les deux-points d’une référence de méthode (::)
     • une esperluette dans un type lié (<T extends Foo & Bar>)
     • un tuyau dans un bloc de capture (catch (FooException | BarException e)).
2. Lorsqu’une ligne est cassée chez un opérateur d’affectation, la rupture vient généralement après le symbole, mais de toute façon est acceptable.
   • Ceci s’applique également aux deux points de type  » opérateur d’affectation » dans une instruction for améliorée (« foreach »).
3. Un nom de méthode ou de constructeur reste attaché à la parenthèse ouverte (() qui le suit.
4. Une virgule (,) reste attachée au jeton qui le précède.
5. Une ligne n’est jamais brisée à côté de la flèche dans un lambda, sauf qu’une rupture peut survenir immédiatement après la flèche si le corps du lambda est constitué d’une seule expression non barrée. Exemples:

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

Remarque: L’objectif principal de l’encapsulation de lignes est d’avoir un code clair, pas nécessairement un code qui tient dans le plus petit nombre de lignes.

4.5.2 Indenter les lignes de continuation au moins +4 espaces

Lors de l’enroulement de ligne, chaque ligne après la première (chaque ligne de continuation) est indentée au moins +4 de la ligne d’origine.

Lorsqu’il y a plusieurs lignes de continuation, l’indentation peut varier au-delà de +4 asdesired. En général, deux lignes de continuation utilisent le même niveau d’indentation si et seulement si elles commencent avec des éléments syntaxiquement parallèles.

La section 4.6.3 sur l’alignement horizontal aborde la pratique découragée d’utiliser un nombre variable d’espaces pour aligner certains jetons avec les lignes précédentes.

4.6 Espaces

4.6.1 Espaces verticaux

Une seule ligne vide apparaît toujours :

1. Entre les membres consécutifs ou les initialiseurs d’une classe: champs, constructeurs, méthodes, classes imbriquées, initialiseurs statiques et initialiseurs d’instance. Exception
   • : Une ligne vide entre deux champs consécutifs (sans autre code entre eux) est facultative. Ces lignes vides sont utilisées au besoin pour créer des regroupements logiques de champs.
   • Exception : Les lignes vides entre les constantes d’énumération sont couvertes dans la section 4.8.1.
2. Tel que requis par d’autres sections de ce document (telles que la Section 3, Structure du fichier source et la Section 3.3, Instructions d’importation).

Une seule ligne vide peut également apparaître partout où elle améliore la lisibilité, par exemple entre les éléments pour organiser le code en sous-sections logiques. Une ligne vide avant le premier membre ou initialiseur, ou après le dernier membre ou initialiseur de la classe, n’est ni encouragée ni encouragée.

Plusieurs lignes vides consécutives sont autorisées, mais jamais requises (ou encouragées).

4.6.2 Espaces horizontaux

Au-delà lorsque requis par la langue ou d’autres règles de style, et à l’exception des littéraux, des commentaires et du JAVADOC, un seul espace ASCII apparaît également aux endroits suivants uniquement.

1. Séparant tout mot réservé, tel que iffor ou catch, d’une parenthèse ouverte (() qui le suit sur cette ligne li>
2. Séparant tout mot réservé, tel que else ou catch, d’une accolade de fermeture (}) qui le précède sur cette ligne
3. Avant toute accolade ouverte ({), à deux exceptions près:
   • @SomeAnnotation({a, b}) (aucun espace n’est utilisé)
   • String x = {{"foo"}}; (aucun espace n’est requis entre {{, par l’élément 8 ci-dessous)
4. Des deux côtés de tout opérateur binaire ou ternaire. Ceci s’applique également aux symboles « de type opérateur » suivants :
   • l’esperluette dans une limite de type conjonctif : <T extends Foo & Bar>
   • le tuyau pour un bloc de capture qui gère plusieurs exceptions: catch (FooException | BarException e)
   • le deux-points (:) dans une instruction for(« foreach »)
   • la flèche dans une expression lambda: (String str) -> str.length()

   mais pas

   • les deux-points (::) d’une référence de méthode, qui s’écrit comme Object::toString
   • le séparateur de points (.), qui s’écrit comme object.toString()
5. Après ,:; ou la parenthèse de fermeture ()) d’une fonte
6. Des deux côtés de la double barre oblique (//) qui commence un commentaire de fin de ligne. Ici, plusieurs espaces sont autorisés, mais pas requis.
7. Entre le type et la variable d’une déclaration : List<String> list
8. Facultatif juste à l’intérieur des deux accolades d’un initialiseur de tableau
   • new int {5, 6} et new int { 5, 6 } sont tous deux valides
9. Entre une annotation de type et ou ....

Cette règle n’est jamais interprétée comme exigeant ou interdisant un espace supplémentaire au début ou à la fin d’une ligne ; elle ne concerne que l’espace intérieur.

4.6.3 Alignement horizontal : jamais requis

Note terminologique: L’alignement horizontal est la pratique consistant à ajouter un nombre variable d’espaces supplémentaires dans votre code dans le but de faire apparaître certains jetons directement sous certains autres jetons des lignes précédentes.

Cette pratique est autorisée, mais n’est jamais requise par Google Style. Il n’est même pas nécessaire de maintenir un alignement horizontal aux endroits où il était déjà utilisé.

Voici un exemple sans alignement, puis en utilisant l’alignement:

private int x; // this is fineprivate Color color; // this tooprivate int x; // permitted, but future editsprivate Color color; // may leave it unaligned

Astuce: L’alignement peut faciliter la lisibilité, mais cela crée des problèmes pour la maintenance future. Envisagez un changement futur qui ne doit toucher qu’une seule ligne. Ce changement peut laisser le formatage autrefois agréable mutilé, et c’est autorisé. Plus souventil invite le codeur (peut-être vous) à ajuster également les espaces sur les lignes voisines, en déclenchant éventuellement une série de reformatages en cascade. Ce changement d’une ligne a maintenant un « rayon de souffle. »Cela peut au pire entraîner un travail inutile, mais au mieux, cela corrompt toujours l’historique des versions, ralentit les réviseurs et exacerbe les conflits de fusion.

4.7 Regroupement des parenthèses: les parenthèses de regroupement facultatives recommandées

ne sont omises que lorsque l’auteur et le réviseur conviennent qu’il n’y a aucune chance raisonnable que le code soit mal interprété sans eux, et qu’ils n’auraient pas rendu le code plus facile à lire. Il n’est pas raisonnable de supposer que chaque lecteur a toute la table de priorité Javaoperator mémorisée.

4.8 Constructions spécifiques

4.8.1 Classes d’énumération

Après chaque virgule qui suit une constante d’énumération, un saut de ligne est facultatif. Des lignes blanches supplémentaires (généralement une seule) sont également autorisées. C’est une possibilité:

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

Une classe enum sans méthodes et sans documentation sur ses constantes peut éventuellement être formatée comme s’il s’agissait d’un initialiseur de tableau (voir Section 4.8.3.1 initialiseurs onarray).

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

Étant donné que les classes enum sont des classes, toutes les autres règles de formatage des classes s’appliquent.

4.8.2 Déclarations de variables

4.8.2.1 Une variable par déclaration

Chaque déclaration de variable (champ ou local) déclare une seule variable : les déclarations telles que int a, b; ne sont pas utilisées.

Exception: Plusieurs déclarations de variables sont acceptables dans l’en-tête d’une boucle for.

4.8.2.2 Déclarées en cas de besoin

Les variables locales ne sont pas habituellement déclarées au début de leur construction contenant un bloc ou de type bloc. Au lieu de cela, les variables locales sont déclarées près du point où elles sont utilisées pour la première fois (dans la limite de la raison), afin de minimiser leur portée. Les déclarations de variables locales ont généralement des initialiseurs ou sont initialisées immédiatement après la déclaration.

4.8.3 Tableaux

4.8.3.1 Initialiseurs de tableaux: peut être « de type bloc »

Tout initialiseur de tableau peut éventuellement être formaté comme s’il s’agissait d’une « construction de type bloc ». »Par exemple, les éléments suivants sont tous valides (pas une liste exhaustive):

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

4.8.3.2 Aucune déclaration de tableau de style C

Les crochets font partie du type, pas de la variable : String args, pas String args.

4.8.4 Instructions Switch

Note terminologique : À l’intérieur des accolades du bloc aswitch se trouvent un ou plusieurs groupes d’instructions. Chaque groupe d’instructions se compose d’une ou plusieurs étiquettes de commutateur (soit case FOO: ou default:), suivies d’une ou plusieurs instructions (ou, pour le dernier groupe d’instructions, de zéro ou plusieurs instructions).

4.8.4.1 Indentation

Comme pour tout autre bloc, le contenu d’un bloc de commutation est indenté +2.

Après une étiquette de commutateur, il y a un saut de ligne et le niveau d’indentation est augmenté de +2, exactement comme si un bloc était ouvert. L’étiquette de commutateur suivante revient au niveau d’indentation précédent, comme si un bloc avait été fermé.

4.8.4.2 Chute: commenté

Dans un bloc de commutation, chaque groupe d’instructions se termine brusquement (avec une exception breakcontinuereturn ou levée), ou est marqué d’un commentaire pour indiquer que l’exécution se poursuivra ou pourrait se poursuivre dans le groupe d’instructions suivant. Tout commentaire qui communique l’idée de chute est suffisant (typiquement // fall through). Ce commentaire spécial n’est pas requis dansle dernier groupe d’instructions du bloc de commutation. Exemple:

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

Notez qu’aucun commentaire n’est nécessaire après case 1:, uniquement à la fin du groupe d’instructions.

4.8.4.3 Le cas defaultest présent

Chaque instruction de commutateur inclut un groupe d’états default, même s’il ne contient aucun code.

Exception : Une instruction switch pour un type enum peut omettre le groupe d’instructions default, s’il inclut des cas explicites couvrant toutes les valeurs possibles de ce type. Cela permet auxEs ou à d’autres outils d’analyse statique d’émettre un avertissement si des cas ont été manqués.

4.8.5 Annotations

Les annotations s’appliquant à une classe, une méthode ou un constructeur apparaissent immédiatement après le bloc de documentation, et chaque annotation est répertoriée sur une ligne propre (c’est-à-dire une annotation par ligne). Ces sauts de ligne ne constituent pas un enveloppement de ligne (Section4.5, Enveloppement de ligne), de sorte que le niveau d’indentation n’est pas augmenté. Exemple :

@Override@Nullablepublic String getNameIfPresent() { ... }

Exception: Une seule annotation sans paramètre peut à la place apparaître avec la première ligne de la signature, par exemple :

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

Les annotations s’appliquant à un champ apparaissent également immédiatement après le bloc de documentation, mais dans ce cas, plusieurs annotations (éventuellement paramétrées) peuvent être répertoriées sur la même ligne ; par exemple :

@Partial @Mock DataLoader loader;

Il n’y a pas de règles spécifiques pour formater des annotations sur des paramètres, des variables locales ou des types.

Cette section traite des commentaires sur la mise en œuvre. Javadoc est adressé séparément danssection 7, Javadoc.

Tout saut de ligne peut être précédé d’un espace arbitraire suivi d’un commentaire d’implémentation.Un tel commentaire rend la ligne non vide.

4.8.6.1 Style de commentaire de bloc

Les commentaires de bloc sont en retrait au même niveau que le code environnant. Ils peuvent être de style /* ... */ ou de style // .... Pour les commentaires multi-lignes /* ... */, les lignes suivantes doivent commencer par * alignées avec * sur la ligne précédente.

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

Les commentaires ne sont pas enfermés dans des cases dessinées avec des astérisques ou d’autres caractères.

Astuce: Lorsque vous écrivez des commentaires sur plusieurs lignes, utilisez le style /* ... */ si vous souhaitez que les formateurs de code automatiques déchirent les lignes si nécessaire (style paragraphe). La plupart des formateurs ne réencapsulent pas les lignes dans les blocs de commentaires de style // ....

4.8.7Modificateurs

Les modificateurs de classe et de membre, lorsqu’ils sont présents, apparaissent dans l’orderrecommandé 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

long – les littéraux entiers valorisés utilisent un suffixe en majuscules L, neverlowercase (pour éviter toute confusion avec le chiffre 1). Par exemple, 3000000000L plutôt que 3000000000l.

5 Nommage

5.1 Règles communes à tous les identificateurs

Les identificateurs utilisent uniquement des lettres et des chiffres ASCII et, dans un petit nombre de cas notés ci-dessous, des traits de soulignement. Ainsi, chaque nom d’identifiant valide est mis en correspondance avec l’expression régulière \w+.

In Google Style, special prefixes or suffixes are not used. For example, thesenames are not Google Style: name_mNames_name and kName.

5.2 Rules by identifier type

5.2.1 Package names

Package names are all lowercase, with consecutive words simply concatenated together (nounderscores). For example, com.example.deepspace, notcom.example.deepSpace orcom.example.deep_space.

5.2.2 Class names

Class names are written in UpperCamelCase.

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 phrases (par exemple, List), mais peuvent parfois être des phrases adjectives ou adjectives à la place (par exemple, Readable).

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

Les classes de test sont nommées en commençant par le nom de la classe qu’elles testent et en se terminant par Test. Par exemple, HashTest ou HashIntegrationTest.

5.2.3 Noms de méthode

Les noms de méthode sont écrits en minuscules.

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

Des traits de soulignement peuvent apparaître dans les noms de méthodes de test JUnit pour séparer les composants logiques de thename, chaque composant étant écrit en minuscules.Un modèle typique est <methodUnderTest>_<state>, par exemple pop_emptyStack. Il n’y a pas de correctfaçon de nommer les méthodes de test.

5.2.4 Noms de constantes

Les noms de constantes utilisent CONSTANT_CASE : toutes les majuscules, chaque mot étant séparé du suivant par un seul trait de soulignement. Mais qu’est-ce qui est exact ?

Les constantes sont des champs finaux statiques dont le contenu est profondément immuable et dont les méthodes ont des effets secondaires non détectables. Cela inclut les primitives, les chaînes, les types immuables et les collections immutables de types immuables. Si l’un des états observables de l’instance peut changer, il n’est pas constant. Le simple fait de ne jamais muter l’objet ne suffit pas. Exemple:

// Constantsstatic 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 immutablestatic final SomeMutableType EMPTY_ARRAY = {};enum SomeEnum { ENUM_CONSTANT }// Not constantsstatic 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"};

Ces noms sont généralement des noms ou des phrases nominales.

5.2.5 Les noms de champs non constants

Les noms de champs non constants (statiques ou autres) sont écrits en minuscules.

Ces noms sont généralement des noms ou des phrases nominales. Par exemple, computedValues ou index.

5.2.6 Noms de paramètres

Les noms de paramètres sont écrits en minuscules.

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

5.2.7 Les noms de variables locales

Les noms de variables locales sont écrits en minuscules.

Même lorsqu’elles sont définitives et immuables, les variables locales ne sont pas considérées comme des constantes et ne doivent pas être qualifiées de constantes.

5.2.8 Noms de variables de type

Chaque variable de type est nommée dans l’un des deux styles suivants :

• Une seule lettre majuscule, éventuellement suivie d’un seul chiffre (tel que ETXT2)
• Un nom sous la forme utilisée pour les classes (voir Section 5.2.2, Noms de classes), suivi de la lettre majuscule T (exemples: RequestTFooBarT).

5.3 Camel case: défini

Il existe parfois plus d’un moyen raisonnable de convertir une phrase anglaise en camel case, par exemple lorsque des acronymes ou des constructions inhabituelles telles que « IPv6 » ou « iOS » sont présents. Pour améliorer la prévisibilité, Google Style spécifie le schéma (presque) déterministe suivant.

En commençant par la forme en prose du nom :

1. Convertissez la phrase en ASCII simple et supprimez les apostrophes. Par exemple, « l’algorithme de Müller » pourrait devenir « l’algorithme de Muellers ».
2. Divisez ce résultat en mots, en divisant les espaces et toute ponctuation restante (généralement des tirets).
   • Recommandé: si un mot a déjà une apparence classique de camel-case dans l’usage courant, divisez-le en ses parties constitutives (par exemple, « AdWords » devient « ad words »). Notez qu’un mot tel que « iOS » n’est pas vraiment dans le cas de camel en soi; il défie toute convention, donc cette recommandation ne s’applique pas.
3. Maintenant tout en minuscules (y compris les acronymes), puis en majuscules seulement le premier caractère de:
   • … chaque mot, pour donner un cas de chameau supérieur, ou
   • … chaque mot sauf le premier, pour donner un cas de chameau inférieur
4. Enfin, joignez tous les mots en un seul identifiant.

Notez que le boîtier des mots originaux est presque entièrement ignoré. Exemple:

Prose form	Correct	Incorrect
« XML HTTP request »	XmlHttpRequest	XMLHTTPRequest
« new customer ID »	newCustomerId	newCustomerID
« inner stopwatch »	innerStopwatch	innerStopWatch
« supports IPv6 on iOS? »	supportsIpv6OnIos	supportsIPv6OnIOS
« YouTube importer »	YouTubeImporter YoutubeImporter*

*Acceptable, but not recommended.

Note: Some words are ambiguously hyphenated in the Englishlanguage: for example « nonempty » and « non-empty » are both correct, so the method namescheckNonempty andcheckNonEmpty are likewise both correct.

6 Programming Practices

6.1 @Override: toujours utilisée

Une méthode est marquée avec l’annotation @Override, quel que soit le moment où elle est légale. Cela comprend une méthode de classe remplaçant une méthode de superclasse, une méthode de classe implémentant une méthode d’interface et une méthode d’interface respectant une méthode de superinterface.

Exception : @Override peut être omis lorsque la méthode parente est @Deprecated.

6.2 Exceptions interceptées: non ignorées

Sauf comme indiqué ci-dessous, il est très rarement correct de ne rien faire en réponse à une exception caughtexception. (Les réponses typiques consistent à le consigner, ou s’il est considéré comme « impossible », à le replanter en tant que AssertionError.)

Lorsqu’il est vraiment approprié de ne prendre aucune action dans un bloc de capture, la raison pour laquelle cela est justifié est expliquée dans un commentaire.

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 sans commentaire si son nom est ou commence par expected. Thefollowing est un idiome très courant pour s’assurer que le code testé lève une exception du type attendu, donc un commentaire n’est pas nécessaire ici.

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

6.3 Membres statiques: qualifiés en utilisant la classe

Lorsqu’une référence à un membre de classe statique doit être qualifiée, elle est qualifiée avec le nom de cette classe, pas avec une référence ou une expression du type de cette classe.

Foo aFoo = ...;Foo.aStaticMethod(); // goodaFoo.aStaticMethod(); // badsomethingThatYieldsAFoo().aStaticMethod(); // very bad

6.4 Finaliseurs : non utilisés

Il est extrêmement rare de remplacer Object.finalize.

Astuce: Ne le faites pas. Si vous le devez absolument, lisez et comprenez d’abord l’élément Java 7 efficace, « Évitez les finaliseurs », très attentivement, puis ne le faites pas.

7 Javadoc

7.1 Formatage

7.1.1 Forme générale

La mise en forme de base des blocs Javadoc est la suivante :

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

… ou dans cet exemple à une seule ligne :

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

La forme de base est toujours acceptable. La forme à une seule ligne peut être substituée lorsque l’intégralité du bloc Javadoc (y compris les marqueurs de commentaires) peut tenir sur une seule ligne. Notez que cela ne s’applique que lorsqu’il n’y a pas de balises de bloc telles que @return.

7.1.2 Paragraphes

Une ligne vide — c’est—à-dire une ligne contenant uniquement l’astérisque de début aligné (*) – apparaît entre les paragraphes et avant le groupe de balises de bloc ifpresent. Chaque paragraphe, mais le premier, a <p> immédiatement avant le premier mot, sans espace après.

7.1.3 Balises de bloc

Toutes les « balises de bloc » standard utilisées apparaissent dans l’ordre @param@return@throws@deprecated, et ces quatre types n’apparaissent jamais avec une description vide. Lorsqu’une balise de bloc ne tient pas sur une seule ligne, les lignes de continuationsont en retrait de quatre (ou plus) espaces à partir de la position de @.

7.2 Le fragment de résumé

Chaque bloc Javadoc commence par un bref fragment de résumé. Ce fragment est très important: c’est la seule partie du texte qui apparaît dans certains contextes tels que les index de classes et de méthodes.

Ceci est un fragment — une phrase nominale ou une phrase verbale, pas une phrase complète. Il ne commence pas par A {@code Foo} is a..., ou This method returns..., ni ne forme une phrase impérative complète comme Save the record.. Cependant, le fragment est en majuscule etpuncté comme s’il s’agissait d’une phrase complète.

Astuce: Une erreur courante consiste à écrire un Javadoc simple sous la forme /** @return the customer ID */. C’est incorrect, et devrait êtrechangé à /** Returns the customer ID. */.

7.3 Où Javadoc est utilisé

Au minimum, Javadoc est présent pour chaque classe public, et tous les membres public ou protected d’une telle classe, à quelques exceptions près notées ci-dessous.

Du contenu Javadoc supplémentaire peut également être présent, comme expliqué à la section 7.3.4, Javadoc non requis.

7.3.1 Exception: méthodes explicites

Javadoc est facultatif pour les méthodes « simples et évidentes » comme getFoo, dans les cas où il n’y a vraiment et vraiment rien d’autre qui vaille la peine de dire, sauf « Retourne le foo ».

Important: il n’est pas approprié de citer cette exception pour justifiermettre des informations pertinentes qu’un lecteur typique pourrait avoir besoin de connaître. Par exemple, pour une méthode nommée getCanonicalName, n’omettez pas sa documentation (avec la justification qu’elle ne dirait que /** Returns the canonical name. */) si un lecteur typique n’a peut-être pas d’ideque signifie le terme « nom canonique »!

7.3.2 Exception : remplace

Javadoc n’est pas toujours présent sur une méthode qui remplace une méthode de supertype.

7.3.4 Javadoc non requis

Les autres classes et membres ont Javadoc selon les besoins ou les souhaits.