Style de code Java AOSP pour les contributeurs

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Les styles de code de cette page sont des règles strictes pour contribuer au code Java dans Projet Android Open Source (AOSP) Contributions à la plate-forme Android qui ne respectent pas ces règles ne sont généralement pas acceptées. Mer que tous les codes existants ne respectent pas ces règles, mais nous nous attendons à nouveau code pour être en conformité. Voir Codage respectueux pour obtenir des exemples de termes à utiliser et à éviter pour un écosystème plus inclusif.

Soyez cohérent

L'une des règles les plus simples est SOYEZ COHÉRENT. Si vous modifiez du code, prenez quelques minutes pour examiner le code environnant et déterminer son style. Si utilise des espaces autour des clauses if. Si le code sont entourées d'une icône en forme d'étoile, ajoutez-les de petites boîtes d’étoiles autour d’eux aussi.

Le but des directives de style est d'avoir un vocabulaire commun de le codage, afin que les lecteurs puissent se concentrer sur ce que vous dites comment vous le dites. Nous présentons ici des règles de style globales le vocabulaire, mais aussi le style local. Si le code que vous ajoutez à un fichier est radicalement différent du code existant qui l'entoure, cela perturbe le rythme des lecteurs lorsqu'ils le lisent. Essayez de éviter cela.

Règles du langage Java

Android respecte les conventions de codage Java standards avec les règles supplémentaires décrites ci-dessous.

Ne pas ignorer les exceptions

Il peut être tentant d'écrire du code qui ignore une exception, par exemple:

  void setServerPort(String value) {
      try {
          serverPort = Integer.parseInt(value);
      } catch (NumberFormatException e) { }
  }

Ne le faites pas. Même si vous pensez peut-être que votre code ne rencontrera jamais ce problème ou qu'il n'est pas important de la gérer, en ignorant ce type de crée des mines dans votre code pour permettre à un autre déclencher un jour. Vous devez gérer chaque exception de votre code dans une selon des principes ; le traitement spécifique varie selon le cas.

"Chaque fois qu'une personne a une clause catch vide, elle doit avoir ressentie. Dans certains cas, c'est la bonne mais au moins vous devez y penser. Avec Java, vous ne pouvez pas échapper à cette sensation effrayante." James Gosling

Les alternatives acceptables (par ordre de préférence) sont les suivantes:

• Générez l'exception à l'appelant de votre méthode.

    void setServerPort(String value) throws NumberFormatException {
        serverPort = Integer.parseInt(value);
    }

• Générez une nouvelle exception adaptée à votre niveau d'abstraction.

    void setServerPort(String value) throws ConfigurationException {
      try {
          serverPort = Integer.parseInt(value);
      } catch (NumberFormatException e) {
          throw new ConfigurationException("Port " + value + " is not valid.");
      }
    }

• Traitez l'erreur de manière optimale et remplacez la valeur appropriée dans le champ Bloc catch {}.

    /** Set port. If value is not a valid number, 80 is substituted. */
  
    void setServerPort(String value) {
      try {
          serverPort = Integer.parseInt(value);
      } catch (NumberFormatException e) {
          serverPort = 80;  // default port for server
      }
    }

• Interceptez l'exception et générez une nouvelle instance de RuntimeException. C'est dangereux, ne le faites que si vous êtes certain que une erreur se produit, la chose appropriée est de planter.

    /** Set port. If value is not a valid number, die. */
  
    void setServerPort(String value) {
      try {
          serverPort = Integer.parseInt(value);
      } catch (NumberFormatException e) {
          throw new RuntimeException("port " + value " is invalid, ", e);
      }
    }

  <ph type="x-smartling-placeholder">
• En dernier recours, si vous êtes sûr qu'ignorer l'exception est approprié, vous pouvez l'ignorer, mais vous devez également expliquer pourquoi avec pour une bonne raison.

  /** If value is not a valid number, original port number is used. */
  
  void setServerPort(String value) {
      try {
          serverPort = Integer.parseInt(value);
      } catch (NumberFormatException e) {
          // Method is documented to just ignore invalid user input.
          // serverPort will just be unchanged.
      }
  }

Ne pas détecter les exceptions génériques

Il peut être tentant d'être paresseux lors de la détection d'exceptions et de faire quelque chose comme ceci:

  try {
      someComplicatedIOFunction();        // may throw IOException
      someComplicatedParsingFunction();   // may throw ParsingException
      someComplicatedSecurityFunction();  // may throw SecurityException
      // phew, made it all the way
  } catch (Exception e) {                 // I'll just catch all exceptions
      handleError();                      // with one generic handler!
  }

Ne le faites pas. Dans la plupart des cas, il est inapproprié d'intercepter Exception ou Throwable (de préférence différent de Throwable) car il inclut Error exceptions). C'est dangereux, car cela signifie que les exceptions auquel vous ne vous attendiez jamais (y compris les exceptions d'exécution telles que ClassCastException) être pris en compte dans la gestion des erreurs au niveau de l'application. Cela masque la défaillance de gestion des propriétés de votre code, c'est-à-dire que si quelqu'un ajoute un nouveau type dans le code que vous appelez, le compilateur ne signale pas que vous devez gérer l'erreur différemment. Dans la plupart des cas, vous ne devrait pas gérer différents types d'exceptions de la même manière.

Les rares exceptions à cette règle sont le code de test et le code de niveau supérieur, où Détecter toutes sortes d'erreurs (pour les empêcher de s'afficher dans une interface utilisateur ou pour exécuter un job par lot). Dans ces cas, vous pouvez rattraper Exception (ou Throwable) générique et gérez l'erreur de manière appropriée. Réfléchissez bien avant de faire cela et ajoutez des commentaires expliquant pourquoi c'est sans danger dans ce contexte.

Alternatives à l'interception des exceptions génériques:

• interceptez chaque exception séparément dans le cadre d'un bloc "multi-catch", par exemple:

  try {
      ...
  } catch (ClassNotFoundException | NoSuchMethodException e) {
      ...
  }

• Refactorisez votre code pour bénéficier d'une gestion plus précise des erreurs avec plusieurs blocs try. Diviser l'E/S de l'analyse et gérer les erreurs séparément dans chaque cas.
• Générez à nouveau l'exception. Souvent, vous n'avez pas besoin d'attraper de toute façon à ce niveau, laissez simplement la méthode la générer.

N'oubliez pas que les exceptions sont vos amis ! Lorsque le compilateur se plaint que vous ne pas intercepter une exception, ne soyez pas à la trompette. Souriez ! Le compilateur vient de plus facile de détecter les problèmes d'exécution dans votre code.

Ne pas utiliser de finaliseurs

Les finaliseurs permettent d'exécuter un bloc de code lorsqu'un objet est de récupération de mémoire. Bien que les finaliseurs puissent être utiles pour le nettoyage (en particulier pour les ressources externes), il n'existe aucune garantie un finaliseur sera appelé (ou même qu'il le sera du tout).

Android n'utilise pas de finaliseurs. Dans la plupart des cas, vous pouvez utiliser une bonne gestion des exceptions. Si vous avez absolument besoin d'un finaliseur, définissez une méthode close() (ou une méthode similaire) et documentez le moment exact doit être appelée (voir InputStream, par exemple). Dans ce cas, il est approprié, mais pas obligatoire, d'imprimer un court message de journal à partir du final, tant qu'il ne doit pas inonder les journaux.

Importations entièrement éligibles

Lorsque vous souhaitez utiliser la classe Bar du package foo, deux cas de figure méthodes possibles pour l'importer:

• import foo.*;

  Réduit potentiellement le nombre d'instructions d'importation.

• import foo.Bar;

  Cela permet de voir clairement quelles classes sont utilisées et le code est plus lisibles par les responsables.

Utilisez import foo.Bar; pour importer tout le code Android. Une une exception explicite est faite pour les bibliothèques Java standards (java.util.*, java.io.*, etc.) et le code de test unitaire (junit.framework.*).

Règles de la bibliothèque Java

Il existe des conventions pour utiliser les outils et bibliothèques Java d'Android. Dans Dans certains cas, la convention a changé de façon importante et le code plus ancien peut utiliser un modèle ou une bibliothèque obsolète. Lorsque vous travaillez avec un tel code, vous pouvez continuer le style existant. Lors de la création de composants mais n'utilisez jamais de bibliothèques obsolètes.

Règles de style Java

Utiliser les commentaires Javadoc standards

Chaque fichier doit comporter une déclaration de droits d'auteur en haut, suivie de Les instructions de package et d'importation (chaque bloc séparé par une ligne vide) et et enfin la déclaration de classe ou d'interface. Dans les commentaires Javadoc, décrire ce que fait la classe ou l'interface.

/*
 * Copyright (C) yyyy The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.android.internal.foo;

import android.os.Blah;
import android.view.Yada;

import java.sql.ResultSet;
import java.sql.SQLException;

/**
 * Does X and Y and provides an abstraction for Z.
 */

public class Foo {
    ...
}

Chaque classe et méthode publique non triviale que vous écrivez doit contenir un commentaire Javadoc contenant au moins une phrase décrivant ce que la classe ou méthode. Cette phrase doit commencer par une troisième personne verbe descriptif.

Exemples

/** Returns the correctly rounded positive square root of a double value. */

static double sqrt(double a) {
    ...
}

ou

/**
 * Constructs a new String by converting the specified array of
 * bytes using the platform's default character encoding.
 */
public String(byte[] bytes) {
    ...
}

Vous n'avez pas besoin d'écrire de Javadoc pour des méthodes "get" et "set" triviales, telles que setFoo() si tout votre Javadoc indique "sets Foo" (définit Foo). Si la méthode effectue quelque chose de plus complexe (comme appliquer une contrainte ou a un effet secondaire important), vous devez alors le documenter. Si ce n'est pas le cas ce que la propriété "Foo" va vous donner signifie que vous devez le documenter.

Chaque méthode que vous écrivez, publique ou autre, bénéficierait de Javadoc. Les méthodes publiques font partie d'une API et nécessitent donc Javadoc. Android n'applique pas de style spécifique pour écrire du code Javadoc commentaires, mais suivez les instructions de l'article Comment écrire des commentaires sur un document pour l'outil Javadoc.

Écrire des méthodes courtes

Lorsque cela est possible, faites en sorte que les méthodes restent petites et ciblées. Nous savons que depuis longtemps sont parfois appropriées, c'est pourquoi aucune limite stricte n'est appliquée à la méthode Si une méthode dépasse 40 lignes ou plus, demandez-vous si elle peut sans nuire à la structure du programme.

Définir des champs aux emplacements standards

Ils définissent les champs en haut du fichier ou juste avant la méthode méthodes qui les utilisent.

Limiter le champ d'application de la variable

Limitez le champ d'application des variables locales. Ce améliore la lisibilité et la facilité de gestion de votre code et réduit la la probabilité d'erreur. Déclarez chaque variable au niveau interne qui contient toutes les utilisations de la variable.

Déclarez les variables locales au point où elles sont utilisées pour la première fois. Presque toutes les déclarations de variables locales doivent contenir un initialiseur. Si vous ne disposez pas encore d'informations suffisantes pour initialiser une variable raisonnablement, différer la déclaration jusqu'à ce que vous le fassiez.

Les instructions try-catch font exception à cette règle. Si une variable est initialisée avec la valeur renvoyée par une méthode qui génère une exception vérifiée, elle doit être initialisé dans un bloc try. Si la valeur doit être utilisée en dehors de le bloc try, il doit alors être déclaré avant le bloc try, où il ne peuvent pas encore être initialisés de manière sensible:

// Instantiate class cl, which represents some sort of Set

Set s = null;
try {
    s = (Set) cl.newInstance();
} catch(IllegalAccessException e) {
    throw new IllegalArgumentException(cl + " not accessible");
} catch(InstantiationException e) {
    throw new IllegalArgumentException(cl + " not instantiable");
}

// Exercise the set
s.addAll(Arrays.asList(args));

Cependant, vous pouvez même éviter ce cas en encapsulant le try-catch dans une méthode:

Set createSet(Class cl) {
    // Instantiate class cl, which represents some sort of Set
    try {
        return (Set) cl.newInstance();
    } catch(IllegalAccessException e) {
        throw new IllegalArgumentException(cl + " not accessible");
    } catch(InstantiationException e) {
        throw new IllegalArgumentException(cl + " not instantiable");
    }
}

...

// Exercise the set
Set s = createSet(cl);
s.addAll(Arrays.asList(args));

Déclarez les variables de boucle dans l'instruction "for" elle-même, sauf si vous avez une bonne raison de le faire:

for (int i = 0; i < n; i++) {
    doSomething(i);
}

et

for (Iterator i = c.iterator(); i.hasNext(); ) {
    doSomethingElse(i.next());
}

Instructions d'importation d'ordres

L'ordre des instructions d'importation est le suivant:

1. Importations Android
2. Importations de tiers (com, junit, net et org)
3. java et javax

Pour correspondre exactement aux paramètres de l'IDE, les importations doivent se présenter comme suit:

• Ordre alphabétique au sein de chaque groupe, avec une majuscule avant la partie inférieure lettres majuscules et minuscules (par exemple, Z avant a)
• séparés par une ligne vide entre chaque groupe principal ; (android, com, junit, net, org, java javax).

À l'origine, aucune exigence de style n'était imposée. changeaient constamment l'ordre ou les développeurs IDE devaient désactiver les fonctionnalités de gestion automatique des importations les importations. Cette réponse a été jugée insatisfaisante. Lorsqu'on lui a posé la question de style Java, styles préférés varient énormément et Android a dû simplement « choisir un ordre et être cohérent ». Nous avons donc choisi un style, mis à jour le guide de style et oblige les IDE à s’y conformer. Nous nous attendons à ce que, Les utilisateurs de l'IDE travaillent sur le code, les importations dans tous les packages correspondront à sans effort supplémentaire de l'équipe d'ingénierie.

Nous avons choisi ce style comme suit:

• Les importations que les gens veulent examiner en premier ont tendance à se trouver en haut (android).
• Les importations que les gens s'intéressent au moins ont tendance à se trouver tout en bas (java).
• Les humains peuvent facilement suivre le style.
• les IDE peuvent suivre le style.

Placer les importations statiques avant toutes les autres importations classées de la même manière que des importations régulières.

Utiliser les espaces pour la mise en retrait

Nous utilisons quatre (4) retraits d'espace pour les blocs et jamais pour les tabulations. En cas de doute, doit être cohérente avec le code environnant.

Nous utilisons huit (8) retraits d'espace pour les retours à la ligne, y compris pour les appels de fonction. et leurs attributions.

Recommandé

Instrument i =
        someLongExpression(that, wouldNotFit, on, one, line);

Non recommandé

Instrument i =
    someLongExpression(that, wouldNotFit, on, one, line);

Respecter les conventions d'attribution de noms des champs

• Les noms de champs non publics et non statiques commencent par m.
• Les noms de champs statiques commencent par s.
• Les autres champs commencent par une lettre minuscule.
• Les champs finaux statiques (constants, profondément immuables) sont ALL_CAPS_WITH_UNDERSCORES.

Exemple :

public class MyClass {
    public static final int SOME_CONSTANT = 42;
    public int publicField;
    private static MyClass sSingleton;
    int mPackagePrivate;
    private int mPrivate;
    protected int mProtected;
}

Utiliser l'accolade standard

Placez les accolades sur la même ligne que le code qui les précède, et non sur la leur:

class MyClass {
    int func() {
        if (something) {
            // ...
        } else if (somethingElse) {
            // ...
        } else {
            // ...
        }
    }
}

Pour une expression conditionnelle, nous avons besoin d'accolades autour des instructions. Exception: si l'intégralité de la condition (la condition et le corps) tient sur une seule ligne, vous peut (sans y être obligé) tout mettre sur une seule ligne. Par exemple, ce est acceptable:

if (condition) {
    body();
}

et cela est acceptable:

if (condition) body();

mais ce n'est pas acceptable:

if (condition)
    body();  // bad!

Limitez la longueur des lignes

Chaque ligne de texte de votre code ne doit pas comporter plus de 100 caractères. Cette règle a fait l'objet de nombreuses discussions, mais la décision demeure que 100 caractères sont la longueur maximale avec les caractères suivants : exceptions :

• Si une ligne de commentaire contient un exemple de commande ou une URL littérale plus longue de 100 caractères, cette ligne peut dépasser 100 caractères pour et la facilité de couper et coller.
• Les lignes d'importation peuvent dépasser la limite, car les humains les voient rarement (cela simplifie également l'écriture dans les outils).

Utiliser des annotations Java standards

Les annotations doivent précéder les autres modificateurs pour la même langue . Les annotations de repère simples (par exemple, @Override) peuvent être répertoriées sur la sur la même ligne avec l'élément de langue. S'il y a plusieurs annotations, ou paramétrées, répertoriez-les par ligne dans par ordre alphabétique.

Pratiques standards Android pour les trois annotations prédéfinies en Java sont:

• Utiliser l'annotation @Deprecated chaque fois que l'utilisation de l'élément annoté est déconseillée. Si vous utilisez l'annotation @Deprecated, vous devez également avoir un élément @deprecated Tag Javadoc et nommer une autre implémentation. De plus, rappelez-vous qu'une méthode @Deprecated est toujours censée fonctionner. Si vous voyez un ancien code comportant une balise Javadoc @deprecated, ajoutez la méthode Annotation @Deprecated.
• Utilisez l'annotation @Override chaque fois une méthode remplace la déclaration ou l'implémentation d'une super-classe. Par exemple, si vous utilisez la balise Javadoc @inheritdocs et que dériver d'une classe (et non d'une interface), vous devez également annoter ce La méthode remplace celle de la classe parente.
• Utiliser l'annotation @SuppressWarnings uniquement dans des circonstances où il est impossible de d'éliminer un avertissement. Si un avertissement passe cette étape éliminer » test, l'annotation @SuppressWarnings doit être pour s'assurer que tous les avertissements reflètent des problèmes réels du code source.

  Lorsqu'une annotation @SuppressWarnings est nécessaire, elle doit être précédé d'un commentaire TODO expliquant l'erreur "impossible de éliminer » . Il identifie normalement la classe incriminée avec une interface gênante. Exemple :

  // TODO: The third-party class com.third.useful.Utility.rotate() needs generics
  @SuppressWarnings("generic-cast")
  List<String> blix = Utility.rotate(blax);

  Lorsqu'une annotation @SuppressWarnings est requise, refactorisez le code pour isoler les éléments logiciels où l'annotation s'applique.

Traiter les acronymes comme des mots

Traitez les acronymes et les abréviations comme des mots dans les variables de nommage, les méthodes, et classes pour rendre les noms plus lisibles:

Comme le JDK et les code bases Android sont incohérents acronymes, il est pratiquement impossible de rester cohérent avec autour du code. Par conséquent, traitez toujours les acronymes comme des mots.

Utiliser les commentaires TODO

Utilisez des commentaires TODO pour du code temporaire, une solution à court terme ou mais pas parfaits. Ces commentaires doivent inclure la chaîne TODO dans tous majuscules, suivi du signe deux-points:

// TODO: Remove this code after the UrlTable2 has been checked in.

et

// TODO: Change this to use a flag instead of a constant.

Si votre TODO se présente sous la forme "Effectuer une action à une date ultérieure" vérifier Vous devez inclure une date spécifique ("Corriger d'ici novembre 2005") ou un événement spécifique ("Supprimer ce code après tous les mixeurs de production le protocole V7").

Consignez avec parcimonie

Bien que la journalisation soit nécessaire, elle a un impact négatif sur et perd son utilité s'il n'est pas maintenu rapide. Les installations de journalisation offrent cinq niveaux de journalisation différents:

• ERROR: à utiliser lorsqu'une erreur fatale s'est produite, c'est-à-dire l'élément aura des conséquences visibles par l'utilisateur et ne pourra pas être récupéré. sans supprimer certaines données, désinstaller des applications, effacer les partitions de données ou reflasher l'intégralité de l'appareil (ou pire). Ce niveau est toujours consigné. Problèmes qui justifient une certaine journalisation au niveau Les ERROR niveaux sont de bons candidats pour un rapport de collecte de statistiques.
• WARNING: à utiliser en cas de grave et d'inattendu c'est-à-dire quelque chose qui aura des conséquences visibles pour l'utilisateur, mais est susceptible d'être récupérée sans perte de données action explicite, comme l'attente ou le redémarrage complet d'une application. à télécharger une nouvelle version d'une application ou à redémarrer appareil. Ce niveau est toujours consigné. Problèmes qui justifient la journalisation au niveau de WARNING peuvent aussi être prises en compte pour la création de rapports de collecte de statistiques.
• INFORMATIVE: permet de signaler qu'un élément intéressant lorsqu'une situation susceptible de se produire d'avoir un impact généralisé, mais n'est pas nécessairement une erreur. Telle doit être enregistrée uniquement par un module qui considère qu'elle est la plus fiable sur ce domaine (pour éviter les doublons journalisation par des composants ne faisant pas autorité. Ce niveau est toujours consigné.
• DEBUG: permet de préciser ce qui se passe sur le un appareil qui pourrait être utile pour enquêter et déboguer comportements. Consignez uniquement ce qui est nécessaire pour recueillir suffisamment des informations sur ce qui se passe avec votre composant. Si vous avez effectué une opération de débogage les journaux dominent le journal, vous devez utiliser la journalisation.

  Ce niveau est consigné même sur les builds. Il est obligatoire doit être entouré d'un bloc if (LOCAL_LOG) ou if LOCAL_LOGD), où LOCAL_LOG[D] est défini. dans votre classe ou sous-composant. pour désactiver cette journalisation. Il ne doit donc pas y avoir de logique active dans un bloc if (LOCAL_LOG). Toute la construction de chaînes pour le journal doit également être placé à l'intérieur Bloc if (LOCAL_LOG). Ne pas refactoriser l'appel de journalisation dans un appel de méthode si cela entraîne la construction d'une chaîne à l'extérieur Bloc if (LOCAL_LOG).

  Un code indique toujours if (localLOGV). Ce est également considéré comme acceptable, même si le nom n'est pas standard.

• VERBOSE: utiliser pour tout le reste. Ce niveau ne concerne enregistré sur les versions de débogage et doit être entouré d'un if (LOCAL_LOGV) (ou équivalent) afin qu'il puisse être compilés par défaut. Toute construction de ficelle est enlevée et doit apparaître à l'intérieur du Bloc if (LOCAL_LOGV).

Notes

• Dans un module donné, sauf au niveau VERBOSE, une erreur ne doivent être signalés qu'une seule fois, si possible. Dans une seule chaîne de les appels de fonction dans un module, seule la fonction la plus interne renvoient l'erreur. Les appelants d'un même module ne doivent ajouter une journalisation si cela permet de mieux isoler le problème.
• Dans une chaîne de modules, autre qu'au niveau VERBOSE, lorsqu'un le module de niveau inférieur détecte les données non valides provenant d'un niveau supérieur , le module de niveau inférieur ne doit consigner cette situation que dans le module le journal DEBUG, et uniquement si la journalisation fournit des informations qui ne sont pas autrement disponibles pour l'appelant. Plus précisément, il n'est pas nécessaire de journalisation des situations où une exception est levée (celle-ci doit qui contiennent toutes les informations pertinentes) ou dont les seules informations est consigné dans un code d'erreur. C'est particulièrement importante dans l'interaction entre le framework et les applications, et les problèmes causés par des applications tierces qui sont correctement géré par le framework ne doit pas déclencher une journalisation à un niveau supérieur à DEBUG niveau. Les seules situations qui doivent déclencher la journalisation Le niveau INFORMATIVE ou supérieur est détecté lorsqu'un module ou une application détecte une erreur à son propre niveau ou provenant d'un niveau inférieur.
• Lorsqu'une condition qui devrait normalement justifier une journalisation est probable se produire à de nombreuses reprises, il peut être judicieux de mettre en œuvre de limitation du débit pour éviter le dépassement des journaux des copies des mêmes informations (ou d'informations très similaires).
• Les pertes de connectivité réseau sont considérées comme courantes et sont totalement attendue et ne doit pas être consignée à titre sans frais. Une perte de réseau la connectivité qui a des conséquences dans une application doit être consignée à le niveau DEBUG ou VERBOSE (selon que les conséquences sont suffisamment graves et inattendues la compilation).
• Disposer d'un système de fichiers complet sur un système de fichiers accessible à ou sur pour le compte d'applications tierces ne doivent pas être consignées à un niveau supérieure à INFORMATIVE.
• Les données non valides provenant d'une source non fiable (y compris tout fichier sur stockage partagé ou données provenant d'un réseau de connexion) est considéré comme prévu et ne devrait pas déclencher journalisation à un niveau supérieur à DEBUG lorsqu'elle est détectée non valide (et même dans ce cas, la journalisation doit être aussi limitée que possible).
• Lorsqu'il est utilisé sur des objets String, l'opérateur + est implicitement crée une instance StringBuilder avec l'ID par défaut la taille de la mémoire tampon (16 caractères) et éventuellement d'autres String temporaires d'objets. Créer explicitement des objets StringBuilder n'est pas plus cher que d'utiliser l'opérateur + par défaut (et peut être beaucoup plus efficace). Gardez à l'esprit que le code qui appelle Log.v() est compilé et exécuté sur les builds, y compris la création des chaînes, même si les journaux ne sont pas lus.
• Toute journalisation destinée à être lue par d'autres personnes et à être disponibles dans les builds doivent être concis sans être cryptiques, et doit être compréhensible. Cela inclut toute journalisation jusqu'au niveau DEBUG.
• Si possible, continuez à vous connecter sur une seule ligne. Les lignes de 80 à 100 caractères maximum acceptable. Évitez les longueurs supérieures à 130 ou 160 caractères environ (y compris la longueur du tag), si possible.
• Si la journalisation indique que la journalisation a réussi, ne l'utilisez jamais à des niveaux supérieurs que VERBOSE.
• Si vous utilisez la journalisation temporaire pour diagnostiquer un problème difficile à résoudre de le reproduire, le conserver au niveau DEBUG ou VERBOSE, et placez-la dans des blocs "if" qui permettent de la désactiver à la compilation.
• Faites attention aux fuites de sécurité dans le journal. Éviter la journalisation privée des informations. En particulier, évitez de consigner des informations sur le contenu protégé. Ceci est particulièrement important lorsque écrire le code d'un framework, car il n'est pas facile de savoir à l'avance ce qui Il ne s'agit pas d'informations privées ni de contenus protégés.
• N'utilisez jamais System.out.println() (ou printf() pour du code natif). System.out et System.err reçoivent redirigé vers /dev/null. Ainsi, vos instructions d'impression ne comportent pas les effets visibles. Cependant, toute la construction de chaînes qui se produit pour ces appels sont quand même exécutés.
• La règle d'or de la journalisation est que vos journaux d'exclure inutilement d'autres journaux du tampon, tout comme d'autres et non la vôtre.

Règles de style Javatests

Suivez les conventions de dénomination des méthodes de test et utilisez un trait de soulignement pour séparer ce qui est testé à partir du cas spécifique testé. Ce style rend il est plus facile de voir quels cas sont testés. Exemple :

testMethod_specificCase1 testMethod_specificCase2

void testIsDistinguishable_protanopia() {
    ColorMatcher colorMatcher = new ColorMatcher(PROTANOPIA)
    assertFalse(colorMatcher.isDistinguishable(Color.RED, Color.BLACK))
    assertTrue(colorMatcher.isDistinguishable(Color.X, Color.Y))
}