Java Language
Code officiel Oracle standard

Introduction

Remarques

Conventions de nommage

Noms de paquets

• Les noms de paquets doivent être en minuscules, sans caractères de soulignement ou autres caractères spéciaux.
• Les noms de package commencent par la partie d'autorité inversée de l'adresse Web de la société du développeur. Cette partie peut être suivie d'une sous-structure de package dépendant de la structure de projet / programme.
• N'utilisez pas le pluriel. Suivez la convention de l'API standard qui utilise par exemple java.lang.annotation et non java.lang.annotations .
• Exemples: com.yourcompany.widget.button , com.yourcompany.core.api

Noms de classe, d'interface et d'énumération

• Les noms de classe et d'énumération doivent généralement être des noms.
• Les noms d'interface doivent généralement être des noms ou des adjectifs se terminant par… able.
• Utilisez la casse mixte avec la première lettre de chaque mot en majuscule (c.-à- d . CamelCase ).
• Correspond à l'expression régulière ^[AZ][a-zA-Z0-9]*$ .
• Utilisez des mots entiers et évitez d'utiliser des abréviations à moins que l'abréviation ne soit plus utilisée que la forme longue.
• Formatez une abréviation en tant que mot si elle fait partie d’un nom de classe plus long.
• Exemples: ArrayList , BigInteger , ArrayIndexOutOfBoundsException , Iterable .

Noms de méthode

Les noms de méthode doivent généralement être des verbes ou d'autres descriptions d'actions

• Ils doivent correspondre à l'expression régulière ^[az][a-zA-Z0-9]*$ .
• Utilisez la casse mixte avec la première lettre en minuscule.
• Exemples: toString , hashCode

Les variables

Les noms de variables doivent être en casse mixte avec la première lettre en minuscule

• Correspond à l'expression régulière ^[az][a-zA-Z0-9]*$
• Recommandation supplémentaire: Variables
• Exemples: elements , currentIndex

Variables de type

Pour les cas simples où peu de variables de type impliquent, utilisez une seule lettre majuscule.

• Correspond à l'expression régulière ^[AZ][0-9]?$
• Si une lettre est plus descriptive qu'une autre (comme K et V pour les clés et les valeurs dans les cartes ou R pour un type de retour de fonction), utilisez-la, sinon utilisez T
• Pour les cas complexes où les variables de type lettre unique deviennent confuses, utilisez des noms plus longs écrits dans toutes les majuscules et utilisez le trait de soulignement ( _ ) pour séparer les mots.
• Exemples: T , V , SRC_VERTEX

Les constantes

Les constantes (champs static final dont le contenu est immuable, par règles de langage ou par convention) doivent être nommées avec toutes les majuscules et le trait de soulignement ( _ ) pour séparer les mots.

• Correspond à l'expression régulière ^[AZ][A-Z0-9]*(_[A-Z0-9]+)*$
• Exemples: BUFFER_SIZE , MAX_LEVEL

Autres directives sur le nommage

• Évitez de masquer / masquer les méthodes, les variables et les variables de type dans les étendues externes.
• Laisser la verbosité du nom correspondre à la taille de la portée. (Par exemple, utilisez des noms descriptifs pour les champs des grandes classes et des noms abrégés pour les variables locales à courte durée de vie.)
• Lorsque vous nommez des membres statiques publics, laissez l'identificateur être auto-descriptif si vous pensez qu'ils seront importés de manière statique.
• Lectures complémentaires: Section de nommage (dans le Guide de style Java officiel)

_{Source: Directives de style Java d'Oracle}

Fichiers source Java

• Toutes les lignes doivent être terminées par un caractère de saut de ligne (LF, valeur ASCII 10) et non par exemple CR ou CR + LF.

• Il ne peut y avoir aucun espace blanc à la fin d'une ligne.

• Le nom d'un fichier source doit être égal au nom de la classe qu'il contient, suivi de l'extension .java , même pour les fichiers ne contenant qu'une classe privée de package. Cela ne s'applique pas aux fichiers ne contenant aucune déclaration de classe, tels que package-info.java .

Caractères spéciaux

• Outre LF, le seul espace blanc autorisé est Space (valeur ASCII 32). Notez que cela implique que les autres caractères d'espace blanc (in, par exemple, les littéraux de chaîne et de caractère) doivent être écrits sous une forme échappée.

• \' , \" , \\ , \t , \b , \r , \f et \n devraient être préférés aux caractères octaux correspondants (par exemple \047 ) ou Unicode (par exemple \u0027 ).

• Au cas où il serait nécessaire de respecter les règles ci-dessus à des fins de test, le test devrait générer l'entrée requise par programmation.

Déclaration de colis

package com.example.my.package;

La déclaration de package ne doit pas être encapsulée, qu'elle dépasse ou non la longueur maximale recommandée d'une ligne.

Déclarations d'importation

// First java/javax packages
import java.util.ArrayList;
import javax.tools.JavaCompiler;

// Then third party libraries
import com.fasterxml.jackson.annotation.JsonProperty;

// Then project imports
import com.example.my.package.ClassA;
import com.example.my.package.ClassB;

// Then static imports (in the same order as above)
import static java.util.stream.Collectors.toList;

• Les déclarations d'importation doivent être triées…

  • … Principalement par non statique / statique avec les importations non statiques en premier.
  • … Secondairement par origine du colis selon l'ordre suivant
    • paquets java
    • paquets javax
    • packages externes (ex: org.xml)
    • packages internes (ex: com.sun)
  • … Tertiaire par colis et identifiant de classe par ordre lexicographique

• Les instructions d'importation ne doivent pas être mises en ligne, même si elles dépassent la longueur maximale recommandée d'une ligne.

• Aucune importation inutilisée ne devrait être présente.

Importations de caractères génériques

• Les importations de caractères génériques ne doivent généralement pas être utilisées.
• Lors de l'importation d'un grand nombre de classes étroitement liées (par exemple, l'implémentation d'un visiteur sur une arborescence comportant des dizaines de classes de «nœuds» distinctes), une importation de caractères génériques peut être utilisée.
• Dans tous les cas, vous ne devez pas utiliser plus d'une importation de caractères génériques par fichier.

Structure de classe

Ordre des membres de la classe

Les membres du groupe doivent être commandés comme suit:

1. Champs (par ordre public, protégé et privé)
2. Constructeurs
3. Méthodes d'usine
4. Autres méthodes (par ordre public, protégé et privé)

Les champs et méthodes de commande principalement par leurs modificateurs d'accès ou leur identifiant ne sont pas requis.

Voici un exemple de cet ordre:

class Example {

    private int i;

    Example(int i) {
        this.i = i;
    }

    static Example getExample(int i) {
        return new Example(i);
    }

    @Override
    public String toString() {
        return "An example [" + i + "]";
    }

}

Groupement des membres du groupe

• Les champs connexes doivent être regroupés.
• Un type imbriqué peut être déclaré juste avant sa première utilisation; sinon il devrait être déclaré avant les champs.
• Les constructeurs et les méthodes surchargées doivent être regroupés par fonctionnalité et classés avec une arité croissante. Cela implique que la délégation entre ces constructions circule vers le bas dans le code.
• Les constructeurs doivent être regroupés sans autres membres entre eux.
• Les variantes surchargées d’une méthode doivent être regroupées sans autres membres.

Modificateurs

class ExampleClass {
    // Access modifiers first (don't do for instance "static public")
    public static void main(String[] args) {
        System.out.println("Hello World");
    }
}

interface ExampleInterface {
    // Avoid 'public' and 'abstract' since they are implicit
    void sayHello();
}

• Les modificateurs doivent aller dans l'ordre suivant

  • Modificateur d'accès ( public / private / protected )
  • abstract
  • static
  • final
  • transient
  • volatile
  • default
  • synchronized
  • native
  • strictfp

• Les modificateurs ne doivent pas être écrits lorsqu'ils sont implicites. Par exemple, les méthodes d'interface ne doivent ni être déclarées public , ni abstract , et les énumérations et les interfaces imbriquées ne doivent pas être déclarés statiques.

• Les paramètres de la méthode et les variables locales ne doivent pas être déclarés final moins d'améliorer la lisibilité ou de documenter une décision de conception réelle.

• Les champs doivent être déclarés final moins qu'il y ait une raison impérieuse de les rendre mutables.

Échancrure

• Le niveau d'indentation est de quatre espaces .
• Seuls les caractères d'espacement peuvent être utilisés pour l'indentation. Pas d'onglets.
• Les lignes vides ne doivent pas être en retrait. (Ceci est impliqué par la règle de non-fin des espaces blancs.)
• case lignes de case doivent être séparées par quatre espaces, et les instructions dans la casse doivent comporter quatre espaces supplémentaires.

switch (var) {
    case TWO:
        setChoice("two");
        break;
    case THREE:
        setChoice("three");
        break;
    default:
        throw new IllegalArgumentException();
}

Reportez-vous aux instructions d'emballage pour obtenir des instructions sur la mise en retrait des lignes de continuation.

Déclarations d'emballage

• Le code source et les commentaires ne doivent généralement pas dépasser 80 caractères par ligne et rarement, voire jamais, 100 caractères par ligne, y compris l'indentation.

  La limite de caractères doit être évaluée au cas par cas. Ce qui compte vraiment, c'est la «densité» sémantique et la lisibilité de la ligne. Rendre les lignes trop longues les rend difficiles à lire; De même, faire des «tentatives héroïques» pour les adapter à 80 colonnes peut aussi les rendre difficiles à lire. La flexibilité décrite ici vise à permettre aux développeurs d’éviter ces extrêmes, et non de maximiser l’utilisation du moniteur immobilier.

• Les URL ou les exemples de commandes ne doivent pas être encapsulés.

// Ok even though it might exceed max line width when indented.
Error e = isTypeParam
        ? Errors.InvalidRepeatableAnnotationNotApplicable(targetContainerType, on)
        : Errors.InvalidRepeatableAnnotationNotApplicableInContext(targetContainerType));

// Wrapping preferable
String pretty = Stream.of(args)
                      .map(Argument::prettyPrint)
                      .collectors(joining(", "));

// Too strict interpretation of max line width. Readability suffers.
Error e = isTypeParam
        ? Errors.InvalidRepeatableAnnotationNotApplicable(
                targetContainerType, on)
        : Errors.InvalidRepeatableAnnotationNotApplicableInContext(
                targetContainerType);

// Should be wrapped even though it fits within the character limit
String pretty = Stream.of(args).map(Argument::prettyPrint).collectors(joining(", "));

• L'emballage à un niveau syntaxique supérieur est préférable à l'emballage à un niveau syntaxique inférieur.

• Il devrait y avoir au plus 1 déclaration par ligne.

• Une ligne de continuation doit être indentée de l’une des quatre manières suivantes

  • Variante 1 : Avec 8 espaces supplémentaires par rapport à l’indentation de la ligne précédente.
  • Variante 2 : Avec 8 espaces supplémentaires par rapport à la colonne de départ de l'expression enveloppée.
  • Variante 3 : Alignée avec l'expression fraternelle précédente (tant qu'il est clair qu'il s'agit d'une ligne de continuation)
  • Variante 4 : Alignée avec l'appel de méthode précédent dans une expression chaînée.

Déclarations de méthode d'emballage

int someMethod(String aString,
               List<Integer> aList,
               Map<String, String> aMap,
               int anInt,
               long aLong,
               Set<Number> aSet,
               double aDouble) {
    …
}

int someMethod(String aString, List<Integer> aList,
        Map<String, String> aMap, int anInt, long aLong,
        double aDouble, long aLong) {
    …
}

int someMethod(String aString,
               List<Map<Integer, StringBuffer>> aListOfMaps,
               Map<String, String> aMap)
        throws IllegalArgumentException {
    …
}

int someMethod(String aString, List<Integer> aList,
        Map<String, String> aMap, int anInt)
                throws IllegalArgumentException {
    …
}

• Les déclarations de méthode peuvent être formatées en répertoriant les arguments verticalement, ou par une nouvelle ligne et +8 espaces supplémentaires
• Si une clause throws doit être encapsulée, placez le saut de ligne devant la clause throws et assurez-vous qu'elle se démarque de la liste des arguments, soit en indentant +8 par rapport à la déclaration de fonction, soit +8 par rapport à la ligne précédente.

Expressions d'emballage

• Si une ligne se rapproche de la limite maximale de caractères, envisagez toujours de la décomposer en plusieurs instructions / expressions au lieu de la limiter.
• Casser avant les opérateurs.
• Pause avant le. dans les appels de méthode chaînés.

popupMsg("Inbox notification: You have "
        + newMsgs + " new messages");

// Don't! Looks like two arguments
popupMsg("Inbox notification: You have " +
         newMsgs + " new messages");

Espace blanc

Espaces verticaux

• Une seule ligne blanche doit être utilisée pour séparer…

  • Déclaration de colis
  • Déclarations de classe
  • Constructeurs
  • Les méthodes
  • Initialisateurs statiques
  • Initialiseurs d'instance

• … Et peuvent être utilisés pour séparer des groupes logiques de

  • déclarations d'importation
  • des champs
  • déclarations

• Plusieurs lignes vierges consécutives ne doivent être utilisées que pour séparer des groupes de membres apparentés et non comme l'espacement standard entre membres.

Espaces horizontaux

• Un seul espace doit être utilisé…

  • Pour séparer les mots-clés des crochets et des accolades voisins
  • Avant et après tous les opérateurs binaires et les opérateurs comme les symboles tels que les flèches dans les expressions lambda et les deux points dans les expressions améliorées pour les boucles (mais pas avant les deux points d'une étiquette)
  • Après // commence un commentaire.
  • Après les virgules séparant les arguments et les points-virgules séparant les parties d'une boucle for.
  • Après la parenthèse de fermeture d'une distribution.

• Dans les déclarations de variables, il n'est pas recommandé d'aligner les types et les variables.

Déclarations variables

• Une variable par déclaration (et au plus une déclaration par ligne)
• Les crochets des tableaux doivent être du type ( String[] args ) et non de la variable ( String args[] ).
• Déclarez une variable locale juste avant sa première utilisation et initialisez-la le plus près possible de la déclaration.

Annotations

Les annotations de déclaration doivent être placées sur une ligne distincte de la déclaration en cours d’annotation.

@SuppressWarnings("unchecked")
public T[] toArray(T[] typeHolder) {
    ...
}

Cependant, peu ou pas d’annotations annotant une méthode à une seule ligne peuvent être placées sur la même ligne que la méthode si elle améliore la lisibilité. Par exemple, on peut écrire:

@Nullable String getName() { return name; }

Pour des raisons de cohérence et de lisibilité, toutes les annotations doivent être placées sur la même ligne ou chaque annotation doit être placée sur une ligne distincte.

// Bad.
@Deprecated @SafeVarargs
@CustomAnnotation
public final Tuple<T> extend(T... elements) {
    ...
}

// Even worse.
@Deprecated @SafeVarargs
@CustomAnnotation public final Tuple<T> extend(T... elements) {
    ...
}

// Good.
@Deprecated
@SafeVarargs
@CustomAnnotation
public final Tuple<T> extend(T... elements) {
    ...
}

// Good.
@Deprecated @SafeVarargs @CustomAnnotation
public final Tuple<T> extend(T... elements) {
    ...
}

Expressions lambda

Runnable r = () -> System.out.println("Hello World");

Supplier<String> c = () -> "Hello World";

// Collection::contains is a simple unary method and its behavior is
// clear from the context. A method reference is preferred here.
appendFilter(goodStrings::contains);

// A lambda expression is easier to understand than just tempMap::put in this case
trackTemperature((time, temp) -> tempMap.put(time, temp));

• Les lambdas d'expression sont préférés aux lambda de bloc à une seule ligne.
• Les références de méthode doivent généralement être préférées aux expressions lambda.
• Pour les références de méthode d'instance liées, ou les méthodes avec une arité supérieure à une, une expression lambda peut être plus facile à comprendre et donc préférable. Surtout si le comportement de la méthode n'est pas clair dans le contexte.
• Les types de paramètres doivent être omis, sauf s'ils améliorent la lisibilité.
• Si une expression lambda s'étend sur plusieurs lignes, envisagez de créer une méthode.

Parenthèses redondantes

return flag ? "yes" : "no";

String cmp = (flag1 != flag2) ? "not equal" : "equal";

// Don't do this
return (flag ? "yes" : "no");

• Les parenthèses de regroupement redondantes (parenthèses n'affectant pas l'évaluation) peuvent être utilisées si elles améliorent la lisibilité.
• Les parenthèses de regroupement redondantes doivent généralement être omises dans des expressions plus courtes impliquant des opérateurs communs, mais incluses dans des expressions plus longues ou des expressions impliquant des opérateurs dont la priorité et l’associativité ne sont pas claires sans parenthèses. Les expressions ternaires avec des conditions non triviales appartiennent à cette dernière.
• L'expression entière qui suit un mot-clé return ne doit pas être entourée de parenthèses.

Littéraux

long l = 5432L;
int i = 0x123 + 0xABC;
byte b = 0b1010;
float f1 = 1 / 5432f;
float f2 = 0.123e4f;
double d1 = 1 / 5432d;  // or 1 / 5432.0
double d2 = 0x1.3p2;

• long littéraux long doivent utiliser le suffixe L majuscule.
• Les littéraux hexadécimaux doivent utiliser les lettres majuscules A - F
• Tous les autres préfixes numériques, infixes et suffixes doivent utiliser des lettres minuscules.

Bretelles

class Example {
    void method(boolean error) {
        if (error) {
            Log.error("Error occurred!");
            System.out.println("Error!");
        } else { // Use braces since the other block uses braces.
            System.out.println("No error");
        }
    }
}

• Les accolades doivent être placées à la fin de la ligne en cours plutôt que sur une ligne.

• Il devrait y avoir une nouvelle ligne devant une accolade à moins que le bloc ne soit vide (voir les formulaires abrégés ci-dessous)

• Les accolades sont recommandées même si le langage les rend facultatives, comme les corps de ligne et les boucles en une seule ligne.

  • Si un bloc s'étend sur plusieurs lignes (commentaires compris), il doit comporter des accolades.
  • Si l'un des blocs d'une instruction if / else a des accolades, l'autre bloc doit également l'être.
  • Si le bloc arrive en dernier dans un bloc englobant, il doit avoir des accolades.

• Le mot-clé else , catch et the while in do…while boucles vont sur la même ligne que l'accolade de fermeture du bloc précédent.

Formes courtes

enum Response { YES, NO, MAYBE }
public boolean isReference() { return true; }

Les recommandations ci-dessus visent à améliorer l'uniformité (et donc à accroître la familiarité et la lisibilité). Dans certains cas, les «formulaires abrégés» qui s'écartent des directives ci-dessus sont tout aussi lisibles et peuvent être utilisés à la place. Ces cas incluent, par exemple, des déclarations d'énumération simples et des méthodes triviales et des expressions lambda.