Serveur d'impression

Style de code Java AOSP pour les contributeurs | Projet Open Source Android – Bien choisir son serveur d impression

Le 29 janvier 2020 - 25 minutes de lecture

Les styles de code sur cette page sont des règles strictes pour la contribution de code Java au
  Projet Open Source Android (AOSP). Contributions à la plateforme Android
  qui n'adhèrent généralement pas à ces règles ne sont pas acceptés. nous
  reconnaître que tout le code existant ne suit pas ces règles, mais nous nous attendons à ce que tous
  nouveau code pour être conforme.

Être cohérent

L'une des règles les plus simples est d'être cohérent. Si vous modifiez du code, prenez quelques
      minutes pour examiner le code environnant et déterminer son style. Si ce
      le code utilise des espaces autour de la si clauses, vous devriez aussi. Si le code
      les commentaires ont de petites boîtes d'étoiles autour d'eux, faites vos commentaires
      de petites boîtes d'étoiles autour d'eux aussi.

Le point d'avoir 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, plutôt que sur
      comment vous le dites. Nous présentons ici des règles de style global pour que vous sachiez
      le vocabulaire, mais le style local est également important. Si le code que vous ajoutez
      à un fichier semble radicalement différent du code existant autour de lui,
      il dérange les lecteurs lorsqu'ils le lisent. Essayez de
      éviter cela.

Règles du langage Java

Android suit les conventions de codage Java standard avec les règles supplémentaires
    décrit ci-dessous.

N'ignorez pas les exceptions

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

  
  
  
  void setServerPort (valeur de chaîne) 
      essayez 
          serverPort = Integer.parseInt (valeur);
       catch (NumberFormatException e) 
  

Ne fais pas ça. Bien que vous puissiez penser que votre code ne rencontrera jamais cela
      condition d'erreur ou qu'il n'est pas important de le gérer, en ignorant ce type de
      exception crée des mines dans votre code pour que quelqu'un d'autre
      déclencher un jour. Vous devez gérer chaque exception de votre code dans un
      manière raisonnée; la manipulation spécifique varie selon les cas.

"Chaque fois que quelqu'un a une clause de capture vide, il devrait avoir un effrayant
      sentiment. Il y a des moments où c'est vraiment le bon
      chose à faire, mais au moins vous devez y penser. En Java, vous ne pouvez pas
      échapper au sentiment effrayant.
"-
James
      Oison

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

  • Remettez l'exception à l'appelant de votre méthode.
      void setServerPort (String value) lève NumberFormatException 
          serverPort = Integer.parseInt (valeur);
      
    
  • Lancez une nouvelle exception adaptée à votre niveau d'abstraction.

      void setServerPort (String value) lève ConfigurationException 
        essayez 
            serverPort = Integer.parseInt (valeur);
         catch (NumberFormatException e) 
            lever une nouvelle ConfigurationException ("Port" + valeur + "n'est pas valide.");
        
      
    
  • Traitez l'erreur avec élégance et remplacez une valeur appropriée dans le
    capture bloquer.

      / ** Définir le port. Si la valeur n'est pas un nombre valide, 80 est substitué. * /
    
      void setServerPort (valeur de chaîne) 
        essayez 
            serverPort = Integer.parseInt (valeur);
         catch (NumberFormatException e) 
            serverPort = 80; // port par défaut pour le serveur
        
      
    
  • Attrapez l'exception et lancez une nouvelle instance de RuntimeException.
            C'est dangereux, alors ne le faites que si vous êtes certain que si cela
            erreur se produit, la chose appropriée à faire est de planter.

      / ** Définir le port. Si la valeur n'est pas un nombre valide, mourez. * /
    
      void setServerPort (valeur de chaîne) 
        essayez 
            serverPort = Integer.parseInt (valeur);
         catch (NumberFormatException e) 
            lever une nouvelle RuntimeException ("port" + valeur "n'est pas valide,", e);
        
      
    
  • En dernier recours, si vous êtes convaincu qu'ignorer l'exception est
            approprié, vous pouvez l'ignorer, mais vous devez également expliquer pourquoi avec
            une bonne raison.

    / ** Si la valeur n'est pas un nombre valide, le numéro de port d'origine est utilisé. * /
    
    void setServerPort (valeur de chaîne) 
        essayez 
            serverPort = Integer.parseInt (valeur);
         catch (NumberFormatException e) 
            // La méthode est documentée pour ignorer les entrées utilisateur non valides.
            // serverPort restera inchangé.
        
    
    

Ne pas intercepter les exceptions génériques

Il peut être tentant d'être paresseux lors de la capture d'exceptions et de faire
      quelque chose comme ça:

  
  
  
  essayez 
      someComplicatedIOFunction (); // peut lancer IOException
      someComplicatedParsingFunction (); // peut lever ParsingException
      someComplicatedSecurityFunction (); // peut lever SecurityException
      // ouf, j'ai tout fait
   catch (Exception e) // Je vais juste attraper toutes les exceptions
      handleError (); // avec un gestionnaire générique!
  

Ne fais pas ça. Dans presque tous les cas, il est inapproprié d'attraper des génériques
Exception ou Throwable (de préférence pas Throwable
car il comprend
Erreur des exceptions). C'est dangereux car cela signifie que les exceptions
      vous ne vous attendiez pas (y compris les exceptions d'exécution comme ClassCastException)
      être pris dans la gestion des erreurs au niveau de l'application. Il masque l'échec
      la gestion des propriétés de votre code, ce qui signifie que si quelqu'un ajoute un nouveau type de
      exception dans le code que vous appelez, le compilateur ne fera pas remarquer
      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.

La rare exception à cette règle est le code de test et le code de niveau supérieur où
      vous voulez intercepter toutes sortes d'erreurs (pour éviter qu'elles n'apparaissent
      dans une interface utilisateur, ou pour maintenir un travail par lots en cours d'exécution). Dans ces cas, vous pouvez attraper
      générique Exception (ou Throwable) et gérer l'erreur de manière appropriée.
      Réfléchissez bien avant de faire cela, et mettez des commentaires
      expliquant pourquoi il est sûr dans ce contexte.

Alternatives à la capture d'exceptions génériques:

N'oubliez pas que les exceptions sont votre ami! Lorsque le compilateur se plaint que vous êtes
      ne pas attraper une exception, ne froncez pas les sourcils. Sourire! Le compilateur vient de le faire
      plus facile pour vous de détecter les problèmes d'exécution dans votre code.

N'utilisez pas de finaliseurs

Les finaliseurs sont un moyen d'exécuter un morceau de code lorsqu'un objet est
      ordures collectées. Les finaliseurs peuvent être utiles pour le nettoyage
      (en particulier des ressources externes), il n’existe aucune garantie quant au
      un finaliseur sera appelé (ou même qu'il sera appelé du tout).

Android n'utilise pas de finaliseurs. Dans la plupart des cas, vous pouvez utiliser
      bonne gestion des exceptions à la place. Si vous avez absolument besoin d'un finaliseur,
      définir un proche() (ou similaire) et documenter exactement quand cela
      doit être appelée (voir
      InputStream pour un exemple). Dans ce cas,
      il est approprié mais pas obligatoire d'imprimer un court message de journal à partir du
      finaliseur, tant qu'il ne devrait pas inonder les journaux.

Qualifier pleinement les importations

Lorsque vous souhaitez utiliser la classe Bar Depuis le paquet foo, il y en a deux
      façons possibles de l'importer:

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

Règles de bibliothèque Java

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

Règles de style Java

Utiliser les commentaires standard Javadoc

Chaque fichier doit avoir une déclaration de copyright en haut, suivie par
      les instructions de package et d'importation (chaque bloc séparé par une ligne vierge), 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 2019 Le projet Open Source Android
 *
 * Sous licence Apache License, Version 2.0 (la "Licence");
 * vous ne pouvez pas utiliser ce fichier sauf en conformité avec la licence.
 * Vous pouvez obtenir une copie de la licence à l'adresse
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Sauf si requis par la loi applicable ou accepté par écrit, le logiciel
 * distribué sous licence est distribué sur une base "en l'état",
 * SANS GARANTIE OU CONDITION D'AUCUNE SORTE, expresse ou implicite.
 * Voir la licence pour la langue spécifique régissant les autorisations et
 * limitations sous la licence.
 * /

package com.android.internal.foo;

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

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

/ **
 * Fait X et Y et fournit une abstraction pour Z.
 * /

classe publique Foo 
    ...

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

Exemples



/ ** Renvoie la racine carrée positive correctement arrondie d'une valeur double. * /

sqrt double statique (double a) 
    ...

ou



/ **
 * Construit une nouvelle chaîne en convertissant le tableau spécifié de
 * octets utilisant l'encodage de caractères par défaut de la plateforme.
 * /
chaîne publique (octet[] octets) 
    ...

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

Chaque méthode que vous écrivez, publique ou non, bénéficierait de Javadoc.
      Les méthodes publiques font partie d'une API et nécessitent donc Javadoc. Android
      n'applique pas un style spécifique pour l'écriture de Javadoc
      commentaires, mais vous devez suivre les instructions de la section Comment écrire des commentaires de document pour l'outil Javadoc.

Écrire des méthodes courtes

Lorsque cela est possible, gardez les méthodes petites et ciblées. Nous reconnaissons que longtemps
      les méthodes sont parfois appropriées, donc aucune limite stricte n'est placée sur la méthode
      longueur. Si une méthode dépasse 40 lignes environ, réfléchissez si elle peut
      être décomposé sans nuire à la structure du programme.

Définir des champs dans des emplacements standard

Définissez les champs soit en haut du fichier, soit immédiatement avant le
      méthodes qui les utilisent.

Limiter la portée variable

Gardez la portée des variables locales au minimum. Cette
      augmente la lisibilité et la maintenabilité de votre code et réduit la
      probabilité d'erreur. Déclarez chaque variable au plus profond
      bloc qui englobe toutes les utilisations de la variable.

Déclarez les variables locales au point où elles sont utilisées pour la première fois.
      Presque chaque déclaration de variable locale doit contenir un initialiseur.
      Si vous n'avez pas encore suffisamment d'informations pour initialiser une variable
      raisonnablement, reporter la déclaration jusqu'à ce que vous le fassiez.

L'exception est les instructions try-catch. Si une variable est initialisée avec
      la valeur de retour d'une méthode qui lève une exception vérifiée, elle doit être
      initialisé dans un bloc try. Si la valeur doit être utilisée en dehors de la
      bloc try, il doit être déclaré avant le bloc try, où il
      ne peut pas encore être initialisé sensiblement:



// Instanciation de la classe cl, qui représente une sorte d'ensemble

Définissez s = null;
essayez 
    s = (Set) cl.newInstance ();
 catch (IllegalAccessException e) 
    lancer une nouvelle exception IllegalArgumentException (cl + "non accessible");
 catch (InstantiationException e) 
    lever une nouvelle exception IllegalArgumentException (cl + "non instanciable");


// Exercer l'ensemble
s.addAll (Arrays.asList (args));

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



Définir createSet (classe cl) 
    // Instanciation de la classe cl, qui représente une sorte d'ensemble
    essayez 
        return (Set) cl.newInstance ();
     catch (IllegalAccessException e) 
        lancer une nouvelle exception IllegalArgumentException (cl + "non accessible");
     catch (InstantiationException e) 
        lever une nouvelle exception IllegalArgumentException (cl + "non instanciable");
    


...

// Exercer l'ensemble
Set s = createSet (cl);
s.addAll (Arrays.asList (args));

Déclarez les variables de boucle dans l'instruction for elle-même, sauf
      il y a une raison impérieuse de faire autrement:



pour (int i = 0; i <n; i ++) 
    doSomething (i);

et



pour (Iterator i = c.iterator (); i.hasNext ();) 
    doSomethingElse (i.next ());

Ordre des déclarations d'importation

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

  1. Importations Android

  2. Importations en provenance de tiers (com, junit,
    net, org)

  3. Java et javax

Pour correspondre exactement aux paramètres IDE, les importations doivent être:

  • Alphabétique dans chaque groupe, avec des majuscules avant le bas
            lettres majuscules (par exemple, Z avant a)

  • Séparé par une ligne vierge entre chaque groupe principal
            (Android, com, junit,
    net, org, Java,
    javax)

À l'origine, il n'y avait aucune exigence de style sur la commande, ce qui signifie que les IDE
      soit toujours changer l'ordre ou les développeurs IDE devaient
      désactiver les fonctions de gestion automatique des importations et maintenir manuellement
      les importations. Cela a été jugé mauvais. Lorsque le style Java a été demandé, le
      les styles préférés variaient énormément et il revenait à Android d'avoir besoin de
      "choisissez simplement une commande et soyez cohérent". Nous avons donc choisi un style,
      mis à jour le guide de style et obligé les IDE à y obéir. Nous nous attendons à ce que
      Les utilisateurs IDE travaillent sur le code, les importations dans tous les packages correspondront à cela
      modèle sans effort d'ingénierie supplémentaire.

Nous avons choisi ce style pour que:

  • Les importations que les gens veulent regarder en premier ont tendance à être au sommet
            (Android).

  • Les importations que les gens veulent regarder au moins ont tendance à être au plus bas
            (Java).

  • Les humains peuvent facilement suivre le style.

  • Les IDE peuvent suivre le style.

Mettre les importations statiques au-dessus de toutes les autres importations ordonnées de la même manière que
      importations régulières.

Utiliser des espaces pour l'indentation

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

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

conseillé



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

Non recommandé



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

Suivez les conventions de dénomination 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 publics (constantes) sont ALL_CAPS_WITH_UNDERSCORES.

Par exemple:



classe publique MyClass 
    public static final int SOME_CONSTANT = 42;
    public int publicField;
    privé statique MyClass sSingleton;
    int mPackagePrivate;
    privé int mPrivate;
    protected int mProtected;

Utiliser un style d'accolade standard

Mettez les accolades sur la même ligne que le code avant eux, pas sur leur propre ligne:



classe MyClass 
    int func () 
        si quelque chose) 
            // ...
         else if (somethingElse) 
            // ...
         autre 
            // ...
        
    

Nous avons besoin d'accolades autour des instructions pour un conditionnel. Exception: si
      l'ensemble conditionnel (la condition et le corps) tient sur une seule ligne, vous
      peut (mais n'est pas obligé de) tout mettre sur une seule ligne. Par exemple, cette
      est acceptable:



si (condition) 
    corps();

et cela est acceptable:

if (condition) body ();

mais ce n'est pas acceptable:



si (condition)
    corps(); // mal!

Limiter la longueur de ligne

Chaque ligne de texte de votre code doit comporter au plus 100 caractères.
      Bien que de nombreuses discussions aient entouré cette règle, la décision reste
      que 100 caractères est le maximum avec ce qui suit
      des 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
            facilité de couper-coller.

  • Les lignes d'importation peuvent dépasser la limite car les humains les voient rarement
            (cela simplifie également l'écriture d'outils).

Utiliser des annotations Java standard

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

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

  • Utilisez le @Deprecated annotation
            chaque fois que l'utilisation de l'élément annoté est déconseillée. Si tu utilises
            le @Deprecated annotation, vous devez également avoir un @deprecated
    Balise Javadoc et il doit nommer une autre implémentation. En plus,
            rappelez-vous qu'un @Deprecated la méthode est toujours censé fonctionner.
            Si vous voyez l'ancien code qui a un @deprecated Balise Javadoc, ajoutez le
    @Deprecated annotation.

  • Utilisez le @Passer outre annotation chaque fois
            une méthode remplace la déclaration ou l'implémentation d'un
            superclasse. Par exemple, si vous utilisez le @inheritdocs Balise Javadoc, et
            dérivent d'une classe (pas d'une interface), vous devez également annoter que
            la méthode remplace la méthode de la classe parente.

  • Utilisez le @Supprimer les avertissements annotation
            seulement dans des circonstances où il est impossible de
            éliminer un avertissement. Si un avertissement passe ce "impossible à
            éliminer "test, le @Supprimer les avertissements annotation doit être
            utilisé, pour garantir que tous les avertissements reflètent des problèmes réels
            code.

    Lorsqu'un @Supprimer les avertissements annotation est nécessaire, elle doit être
              précédé d'un FAIRE commentaire qui explique le «impossible de
              éliminer "condition. Cela identifie normalement une classe fautive
              qui a une interface maladroite. Par exemple:

    
    
    // TODO: La classe tierce com.third.useful.Utility.rotate () a besoin de génériques
    @SuppressWarnings ("générique-cast")
    liste blix = Utility.rotate (blax);
    

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

Traitez les acronymes comme des mots

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

Bien Mal
XmlHttpRequest XMLHTTPRequest
getCustomerId getCustomerID
classe Html classe HTML
URL de chaîne URL de chaîne
long id long ID

Comme le JDK et les bases de code Android ne sont pas cohérents
      acronymes, il est pratiquement impossible d’être cohérent avec les
      code environnant. Par conséquent, traitez toujours les acronymes comme des mots.

Utilisation FAIRE des commentaires pour du code temporaire, une solution à court terme, ou
      assez bon mais pas parfait. Ces commentaires doivent inclure la chaîne FAIRE dans tout
      des majuscules, suivies de deux points:



// TODO: supprimez ce code une fois que UrlTable2 a été archivé.

et



// TODO: Modifiez ceci pour utiliser un drapeau au lieu d'une constante.

Si votre FAIRE est de la forme «À une date future, faites quelque chose» assurez-vous
      que vous incluez une date spécifique ("Fix by November 2005") ou
      un événement spécifique ("Supprimer ce code après tous les mélangeurs de production
      comprendre le protocole V7. ").

Connectez-vous avec parcimonie

Si la journalisation est nécessaire, elle a un impact négatif sur
      performances et perd son utilité si elle n'est pas conservée
      laconique. Les installations de journalisation offrent cinq niveaux différents de journalisation:

  • ERREUR: À utiliser lorsque quelque chose de fatal s'est produit, c'est-à-dire
            quelque chose aura des conséquences visibles par l'utilisateur et ne sera pas récupérable
            sans supprimer certaines données, désinstaller des applications,
            effacer les partitions de données ou reflasher l'ensemble de l'appareil (ou pire).
            Ce niveau est toujours enregistré. Problèmes qui justifient une connexion au
    ERREUR sont de bons candidats à signaler à un
            serveur de collecte de statistiques.
  • AVERTISSEMENT: À utiliser lorsque quelque chose de grave et d'inattendu
            est arrivé, c'est-à-dire quelque chose qui aura des conséquences visibles par l'utilisateur, mais
            est susceptible d'être récupérable sans perte de données en effectuant certains
            action explicite, allant de l'attente ou du redémarrage d'une application jusqu'au bout
            pour re-télécharger une nouvelle version d'une application ou redémarrer le
            dispositif. Ce niveau est toujours enregistré. Problèmes justifiant la journalisation
            au AVERTISSEMENT pourrait également être envisagé pour faire rapport à un
            serveur de collecte de statistiques.
  • INFORMATIF: Utilisez pour noter que quelque chose d'intéressant
            est arrivé, c'est-à-dire lorsqu'une situation est susceptible d'être détectée
            d'avoir un impact généralisé, mais ce n'est pas nécessairement une erreur. Tel que
            condition ne doit être enregistrée par un module qui croit
            qu'il est le plus faisant autorité dans ce domaine (pour éviter les doublons
            journalisation par des composants non autorisés). Ce niveau est toujours enregistré.
  • DÉBOGUER: Permet de noter davantage ce qui se passe sur le
            appareil qui pourrait être pertinent pour enquêter et déboguer de manière inattendue
            comportements. Enregistrez uniquement ce qui est nécessaire pour en rassembler suffisamment
            des informations sur ce qui se passe avec votre composant. Si votre débogage
            les journaux dominent le journal, vous devez utiliser verbeux
            enregistrement.

    Ce niveau est enregistré même sur les versions de versions et est requis
              être entouré d'un if (LOCAL_LOG) ou si
              LOCAL_LOGD)
    bloc, où LOCAL_LOG[D] est défini
              dans votre classe ou sous-composante, afin qu'il y ait une possibilité
              pour désactiver toute cette journalisation. Par conséquent, il ne doit pas y avoir de logique active
              dans un if (LOCAL_LOG) bloquer. Toute la chaîne de construction pour
              le journal doit également être placé à l'intérieur du
    if (LOCAL_LOG) bloquer. Ne refactorisez pas l'appel de journalisation
              dans un appel de méthode si cela va provoquer la
              la construction de cordes aura lieu en dehors de la
    if (LOCAL_LOG) bloquer.

    Il y a du code qui dit encore if (localLOGV). Cette
              est également considéré comme acceptable, bien que le nom ne soit pas standard.

  • VERBEUX: Utilisez pour tout le reste. Ce niveau est uniquement
            connecté sur les versions de débogage et doit être entouré d'un
    if (LOCAL_LOGV) bloc (ou équivalent) afin qu'il puisse être
            compilé par défaut. Tout bâtiment de chaîne est retiré de
            versions et doit apparaître à l'intérieur du
    if (LOCAL_LOGV) bloquer.

Remarques

  • Au sein d'un module donné, autre qu'au niveau VERBEUX niveau, une erreur
              ne doit être signalé qu'une seule fois si possible. Au sein d'une seule chaîne de
              appels de fonction dans un module, seule la fonction la plus interne doit
              retourner l'erreur, et les appelants dans le même module ne devraient ajouter
              une certaine journalisation si cela aide à isoler le problème de manière significative.

  • Dans une chaîne de modules, autre que VERBEUX niveau, lorsqu'un
              le module de niveau inférieur détecte les données invalides provenant d'un niveau supérieur
              module, le module de niveau inférieur ne doit consigner cette situation que dans le
    DÉBOGUER journal, et uniquement si la journalisation fournit des informations qui ne sont pas
              autrement disponible pour l'appelant. Plus précisément, il n'est pas nécessaire de
              consigner les situations où une exception est levée (l'exception doit
              contiennent toutes les informations pertinentes), ou lorsque les seules informations
              étant connecté est contenu dans un code d'erreur. C’est surtout
              important dans l'interaction entre le framework et les applications,
              et conditions causées par des applications tierces correctement
              géré par le cadre ne doit pas déclencher une journalisation supérieure à la
    DÉBOGUER niveau. Les seules situations qui devraient déclencher la journalisation au niveau
    INFORMATIF niveau ou supérieur est lorsqu'un module ou une application détecte
              une erreur à son niveau ou provenant d'un niveau inférieur.

  • Lorsqu'une condition qui justifierait normalement une journalisation est probable
              se produire plusieurs fois, il peut être judicieux de mettre en œuvre certains
              mécanisme de limitation de débit pour éviter de déborder les journaux avec de nombreux
              des copies en double des mêmes informations (ou très similaires).

  • Les pertes de connectivité réseau sont considérées comme courantes et sont entièrement
              attendu, et ne doit pas être enregistré gratuitement. Une perte de réseau
              la connectivité qui a des conséquences dans une application doit être connectée à
              le DÉBOGUER ou VERBEUX niveau (selon que le
              les conséquences sont suffisamment graves et assez inattendues pour être enregistrées dans une version
              construire).

  • Avoir un système de fichiers complet sur un système de fichiers accessible à ou sur
              le nom des applications tierces ne doit pas être enregistré à un niveau
              supérieur à INFORMATIVE.

  • Données non valides provenant de toute source non fiable (y compris tout fichier sur
              stockage partagé ou données provenant d'un réseau
              est considérée comme attendue et ne doit déclencher aucune
              enregistrement à un niveau supérieur à DÉBOGUER quand il est détecté
              invalide (et même alors, la journalisation doit être aussi limitée que possible).

  • Lorsqu'il est utilisé sur Chaîne objets, + opérateur implicitement
              crée un StringBuilder par exemple avec la valeur par défaut
              taille du tampon (16 caractères) et éventuellement d'autres temporaires Chaîne
    objets. Créer donc explicitement StringBuilder les objets ne sont plus
              cher que de compter sur la valeur par défaut + opérateur (et peut être beaucoup
              plus efficace). Gardez à l'esprit ce code qui appelle
    Log.v () est compilé et exécuté sur les versions de versions,
              y compris la construction des chaînes, même si les journaux ne sont pas lus.

  • Toute journalisation destinée à être lue par d'autres personnes et à être
              les versions disponibles doivent être concises sans être cryptiques,
              et doit être compréhensible. Cela inclut tous les enregistrements
              jusqu'à la DÉBOGUER niveau.

  • Lorsque cela est possible, continuez de vous connecter sur une seule ligne.
              Les longueurs de ligne jusqu'à 80 ou 100 caractères sont
              acceptable. Évitez les longueurs supérieures à 130 ou 160 caractères
              (y compris la longueur de la balise) si possible.

  • Si la journalisation rapporte des succès, ne l'utilisez jamais à des niveaux supérieurs
              que VERBEUX.

  • Si vous utilisez la journalisation temporaire pour diagnostiquer un problème difficile à résoudre
              reproduire, le garder à la DÉBOGUER ou VERBEUX niveau et
              l'enfermer avec des blocs if qui permettent de le désactiver à
              compiler le temps.

  • Faites attention aux fuites de sécurité dans le journal. Évitez de vous connecter en privé
              information. En particulier, évitez de consigner des informations sur le contenu protégé.
              Ceci est particulièrement important lorsque
              écrire du code cadre car il n'est pas facile de savoir à l'avance ce qui
              et ne seront pas des informations privées ou du contenu protégé.

  • Ne jamais utiliser System.out.println () (ou printf () pour
              code natif). System.out et System.err avoir
              redirigé vers / dev / null, vos relevés imprimés n'ont donc pas
              effets visibles. Cependant, toute la construction de chaînes qui se produit pour
              ces appels sont toujours exécutés.

  • La règle d'or de la journalisation est que vos journaux ne peuvent pas
              pousser inutilement d'autres journaux hors du tampon, tout comme d'autres
              pas pousser le 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 fait
    il est plus facile de voir quels cas sont testés. Par exemple:



testMethod_specificCase1 testMethod_specificCase2

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

Commentaires

Laisser un commentaire

Votre commentaire sera révisé par les administrateurs si besoin.