Cahier des normes

Les normes Beausoleil sont basées sur celles Google pour Java en 2018, disponibles ici: https://google.github.io/styleguide/javaguide.html

Ce document ne présente que les amendements faits au cahier de normes de Google.

4.1.1 Braces are used where optional Mettez les accolades seulement lorsque nécessaire

Ignorez la section 4.1.1 du document des normes de Google. S'il n’est pas nécessaire de mettre des {}, ne les mettez pas, sauf si cela semble nécessaire pour des raisons de clarté. Un exemple d’une bonne raison de mettre des accolades est lorsque votre “ligne unique” de code est séparée sur plusieurs lignes.

4.1.3 Empty blocks: may be concise

Remplacez par: Un bloc vide est terminé par un point-virgule ( ; ) si possible, autrement deux accolades sur la même ligne. Dans les deux cas, si le bloc vide fait partie d'une déclaration multi-bloc et qu'il y a un bloc qui suit, plutôt utiliser des accolades sur lignes différent, l'accolade fermante sur la même ligne que la déclaration du bloc suivant.

    // Bons exemples
    while (/* condition */);
    
    public void doSomething() {} 
    
    if (/* condition 1*/) {
        doSomething();
    } else if (/* condition 2 */) {
    } else {
        doSomething();
     }

L'utilisation du point-virgule lorsque possible rend absolument claire qu'il ne s'agit pas tant d'un bloc d'instructions mais plutôt de la même opération répétée plusieurs fois et qui fournit sa propre sortie.

4.2 Block indentation: +2 +4 spaces

4.4 Column limit

Le nombre limite de caractères dans une ligne de code Java est de 120 caractères et non pas 100. Cela a pour objectif d'encourager l'utilisation de noms descriptifs, même s'ils sont long.

4.5.2 Indent continuation lines at least +4 spaces

Lorsqu'une ligne est brisée, vous pouvez ou bien la continuer avec deux degrés d'indentation (sois 8 espaces) ou l'aligner avec le dernier degré de déclaration.

// Exemple 1
protected generateMethodPanel generateMethodPanel(Object invocationTarget, Method method,
        Frame frame, String[] names) {
    ...
}

// Exemple 2
Foo bar = new FooBuilder().setName("Exemple")
                          .setAncestor(null)
                          .setId(0)
                          .make();

7.1.3 Block tag

Amendement: Un bloc @param peut être vide si le nom de la variable est évident par lui-même ou dans les getters/setters qui ne font rien de plus que ce que des getters/setters font normalement. Exemple du premier cas:

    public static void banUser(User userToBan) {
	// Ban the user
    }

Ceci est pour éviter de passer du temps à écrire de la documentation qui est auto-évidente.

Ajouts

8 Utilisation de var

Il est permit d'utiliser le mot-clé var uniquement lorsque la variable est déclarée de manière explicite à l'aide d'un constructeur. var est utile pour éviter de se répéter, mais il ne faut pas que son utilisation obfusque le code.

    var foo = new Foo(); // Bon
    var bar = foo.getBar(); // Pas bon. On a aucune idée quel est le type de bar sans regarder la signature de getBar().

9 La valeur nulle

Le concept de null est sujet à débat dans les communautés de développement informatique. L'utilisation de null est permise, mais doit être documentée s'il y a possibilité qu'une telle valeur soit retournée par une fonction. Considérez aussi la possibilité de lancer une exception plutôt que de retourner une valeur nulle dans les contextes où il est possible pour l'utilisateur non averti d'appeler pour des résultats que vous ne pouvez pas fournir.

9.1 La classe Optional

Alternativement, la classe Optional permet de dénoter des éléments de signature de méthodes qui peuvent être null. Utiliser cette classe est une manière d'avoir un code qui est dit self-documenting.

Optional is primarily intended for use as a method return type where there is a clear need to represent "no result," and where using null is likely to cause errors. A variable whose type is Optional should never itself be null; it should always point to an Optional instance. : De l'API Java 8

10 Classes utilitaires et de services

Une classe utilitaire ou de services est une classe contenant uniquement des méthodes et des attributs statiques.

10.1 Classes utilitaires

Les classes utilitaires finissent avec le suffixe "Util".

10.2 Classes de services

Les classes de services pour une classe spécifique portent le nom de la classe à laquelle elle sert de service avec un "s" ajouté à la fin. Si la classe en question finit déjà par "s", utilisez plutôt le suffixe "Service".

10.3 Les classes utilitaires et de services ne sont pas des objets

Les classes utilitaires et de services ne sont pas des objets. Il faut donc empêcher leur instanciation. Il faut donc ajouter le modificateur final à la déclaration de classe pour qu'elle ne soit pas étendue et un constructeur vide privé doit être ajouté pour prévenir leur instanciation.

public final class FooUtil {
    private FooUtil() {}
    ...
}

SBeausoleil/Cahier Normes.md