Directives de codage Java pour un code sans erreur
Nous présentons aujourd'hui un aperçu détaillé des directives de codage Java pour aider les programmeurs et les testeurs d'automatisation. Que vous soyez dans le développement Java ou que vous utilisiez Java pour les tests d'automatisation, vous pouvez utiliser cet article pour améliorer votre style de codage. À l'aide de ces directives de codage Java, vous serez en mesure d'écrire un code robuste, lisible, rectifiable et réutilisable.
- Robuste – Sans erreur et efficace
- Lisible – Facilement lu et compris
- Rectifiable – Correctement documenté
- Réutilisable – Capable d'être réutilisé
Notre objectif est de fournir un chemin vers une pratique cohérente lors du codage en langage Java. Ces directives s'appliquent à tous les types d'activités de codage de logiciels utilisant le langage Java.
Directives et meilleures pratiques de codage Java
- Structure de fichiers pour les fichiers source Java
- Consignes de dénomination des fichiers
- Structure des répertoires
- Structure du fichier
- Structure de classe pour les fichiers source Java
- En-tête de classe
- Déclarations de champs variables statiques/d'instance
- Initialisation statique
- Déclarations de classe interne de membres statiques
- Déclarations de méthode
- Initiateur d'instance
- Déclarations du constructeur
- Consignes de dénomination
- Concepts généraux de la dénomination
- Convention de dénomination des articles
- Consignes relatives au style du code source
- Espacement des lignes
- Espace vide
- Si/sinon
- Pour
- Pendant que
- Faire… Pendant que
- Changer
- Essayer/Attraper/Enfin
- Commentaires.
- Bloquer les commentaires
- Commentaires de fin
- Commentaires sur une seule ligne
- Commentaires sur la documentation
- Conventions de codage Java standard
- Déclarations
- Déclarations
- Déclaration d'importation
- Espaces vides
- Indentation
- Lignes de continuation
- Commentaires sur la documentation des membres
- Déclarations de champs de variables de classe et d'instance
- Gestion des exceptions
- Plug-ins Eclipse pour le style de code
1.1- Structure des fichiers pour les fichiers source Java
Voyons d'abord ce que disent les directives de codage Java à propos de la gestion des fichiers.
1.1.1- Consignes de nommage des fichiers.
Les programmes Java doivent utiliser les suffixes de fichier suivants.
| Type de fichier | Suffixe |
| Source Java | .java |
| Fichiers de classe | .class |
| Nom de l'archive | .jar ou .zip |
Remarque : Le nom du fichier source Java doit être le même que le nom de la classe ou de l'interface contenu dans ce fichier.
1.1.2- Structure des répertoires
/***************** * Project Catalog: ***************** | | |------------- Docs => for project related document. | | |------------- Source => for all the source files. | | | |-------- packageA => for source files related to packageA. | | | |-------- packageB => for source files related to packageB. | | |------------- Target => for all the class files. | | | |-------- packageA => for class files related to packageA. | | | |-------- packageB => for class files related to packageB. | | ******* * Note: A file should contain only one public class in it. ******* */
1.1.3- Structure des fichiers
Conformément aux directives de codage Java, le projet doit inclure les sections suivantes.
- En-tête de fichier.
- Nom du package.
- Importations.
- Définition de classe.
1.1.3.1- En-tête de fichier
Incluez un en-tête de fichier comme indiqué ci-dessous.
/*********************************************************************** #File header layout. File Name : Principal Author : Subsystem Name : Module Name : Date of First Release : Author : Description : #Change History. Version : Date(DD/MM/YYYY) : Modified by : Description of change : ***********************************************************************/
1.1.3.2- Nom du paquet
Les noms de packages doivent apparaître sur la première ligne non commentée du fichier source et doivent suivre les conventions de dénomination définies dans ce document.
1.1.3.3- Importations
Immédiatement après le nom du package, les noms de classe importés doivent figurer.
1.1.3.4- Définition de classe
Immédiatement après les importations devrait être la définition de la classe. L'organisation de la classe est décrite dans la section suivante.
1.2- Structure de classe pour les fichiers source Java
Une classe Java doit comprendre les sections suivantes.
1- En-tête de classe.
2- Déclarations de champs variables statiques/d'instance.
3- Initialiseur statique.
4- Déclarations de classe interne des membres statiques.
5- Déclarations de méthode.
6- Initialiseur d'instance.
7- Déclarations du constructeur d'instance.
Remarque : L'instance de classe, les variables statiques et les méthodes doivent tomber dans l'ordre d'accessibilité public, protégé, par défaut, puis privé. Tous les champs publics doivent avoir un commentaire de documentation.
1.2.1- En-tête de classe
L'en-tête de classe doit être inclus comme indiqué dans le format ci-dessous.
/** * Java class layout. * @deprecated * @see ClassName * @see ClassName#memberFunctionName * @version text * @author authorName * @since */
1.2.2- Déclarations des champs statiques/variables d'instance
Les variables statiques doivent venir en premier et commencer leur déclaration par le mot-clé
Exemple
static private int counter, serial; // Incorrect static private int counter; // Correct static private long serial; // Correct
Certains des points importants que vous devriez noter.
- Toujours obtenir les déclarations de champ sur des lignes séparées.
- Un champ ou une classe qui ne change pas après l'initialisation doit être déclaré final. Cette approche permet au compilateur de générer un meilleur code.
- Assurez-vous d'aligner les noms de champs afin qu'ils commencent tous dans la même colonne.
- Ne laissez aucune variable sans les spécificateurs d'accès.
1.2.3- Initialiseur statique
Un initialiseur statique, le cas échéant, vient ensuite. Il doit avoir la forme suivante.
static {
statements;
}
1.2.4- Déclarations de classe interne des membres statiques
Les classes internes qui sont statiques devraient venir ensuite. Et ces classes doivent suivre la structure suivante.
public class Outer {
static class Inner { // static inner class
}
} 1.2.5- Déclarations de méthode
Chaque méthode Java doit avoir une description liée dans
/** * Description about the Method. * * @param name desc * @exception name desc * @return desc * @see ClassName * @deprecated * @version text * @author authorName * @since */
Les méthodes standards peuvent éviter une description si elles sont regroupées à l'aide de l'un des regroupements logiques suivants.
1- Usine
2- Privé
3- Protégé
4- Interfaces
5- Accesseur
6- Temporel
7- E/S
8- Débogage
Exemple
/* ======================================================= *
Factory Methods (usually static).
* ======================================================= */
/** brief summary.*/
public testClass initbject(void){ }
/* ======================================================= *
Accessor Methods.
* ======================================================= */
public int getObjectState(void);
public void setObjectState(int value);
/* ======================================================= *
Standard Methods.
* ======================================================= */
// anything it could be.
/* ======================================================= *
Debugging Methods.
* ======================================================= */
void doRunTests(void); 1.2.6- Initialiseur d'instance
Un initialiseur d'instance (non statique), le cas échéant, vient ensuite.
1.2.7- Déclarations des constructeurs
Les déclarations de constructeur, le cas échéant, viennent ensuite.
Exemple
public testClass(); public testClass(testClass source);
S'il existe plusieurs constructeurs et que certains ont plus de paramètres, ils doivent apparaître après ceux qui ont moins de paramètres. Cela signifie qu'un constructeur sans argument doit toujours être le premier.
1.3- Consignes de nommage
C'est l'une des directives de codage Java qui dépend du contexte dans lequel vous vous trouvez. En savoir plus à ce sujet.
1.3.1- Concepts généraux de Naming
1- Suivez la stratégie de dénomination liée au domaine.
2- Utilisez la casse des phrases pour rendre les noms lisibles.
3- Soyez réticent lorsque vous utilisez des abréviations.
4- Empêcher l'utilisation de noms redondants qui ne diffèrent que par la casse.
1.3.2- Convention de dénomination des articles
1.3.2.1- Arguments ou paramètres
Utilisez un nom associé pour la valeur/l'objet transmis, et préfixez avec
par exemple argEmpName, paramSalary etc.
1.3.2.2- Champs et Variables
Commencez le nom du champ/de la variable en minuscules, puis continuez dans la casse de la phrase.
par exemple cliquez sur CheckBox, viewInfo, openWindow.
N'utilisez pas de traits de soulignement pour commencer ou séparer les mots.
1.3.2.3- Constantes
Utilisez des majuscules et des traits de soulignement pour former des constantes.
par exemple statique final int MAX_SIZE =256 ;
chaîne finale statique BROWSER_TYPE ="Chrome" ;
1.3.2.4- Classes et interface
Commencez toujours les noms de classe/d'interface par une lettre majuscule.
par exemple Nom de la classe : PageFactory ou PageObject.
Nom de l'interface : IPageObjectModel
1.3.2.5- Fichiers de l'unité de compilation
Utilisez le nom de la classe ou de l'interface précédé de <.java> pour représenter qu'il s'agit d'un fichier de code source.
par exemple TestPage.java, UIMap.java, LoginPage.java.
1.3.2.6- Composant
Utilisez un nom significatif avec un suffixe approprié.
par exemple categoryMenu, listView etc.
1.3.2.7- Forfaits
Démarrez le nom du package avec des noms de domaine de premier niveau uniques tels que com, edu, gov, etc. Suivez les normes ISO 3166, 1981. La partie restante peut varier en fonction de la dénomination interne d'une organisation. structure.
par exemple com.techbeamers.testpackage.
1.3.2.8- Fonction membre
Avoir un nom de fonction qui se rapporte à la tâche à laquelle elle est destinée. Commencez-le avec un verbe actif chaque fois que possible.
Quelques bonnes pratiques de dénomination
Bons noms de méthodes
showStatus(), drawCircle(), addLayoutComponent().
Noms de méthode incorrects
menuButton() – locution nominale ; ne décrit pas la fonction.
OpenTab() – commence par une lettre majuscule.
click_first_menu() – utilise des traits de soulignement.
Fonctions booléennes des membres getter
C'est une bonne pratique de préfixer les fonctions getter booléennes avec
par exemple isVisible(), isChecked(), isNumeric().
Fonctions membres Getter
Habituellement, toutes les fonctions getter doivent commencer par le préfixe
par exemple getLocalDate(), getMonth(), getDayOfMonth().
Fonctions des membres Setter
Habituellement, toutes les fonctions de définition doivent commencer par le préfixe
par ex. setLocalDate(), setMonth(), setDayOfMonth().
Remarque : Les fonctions Getter/Setter doivent suivre des directives strictes pour les classes Java Bean.
1.4- Consignes de style du code source
1.4.1- Interligne
1- Limitez chaque ligne à moins de 80 caractères.
2- Limitez la longueur des commentaires à 70 caractères.
3- Conservez des tailles de tabulation égales à 4 espaces.
1.4.2- Espace vide
Laissez un espace entre les opérateurs et les expressions.
average = average + sum;
while ( average += sum ) {
} 1.4.3- Si/sinon
L'instruction if…else doit respecter le format suivant.
if (expression)
if (expression)
{
{
statement;
statement;
} else
}
elseif(expression)
{
{
statement;
statement;
}
} 1.4.4- Boucle For
Une instruction de boucle for doit respecter le format suivant.
for (initialization; condition; update)
{
statements;
} Dans la version JDK 1.5, une nouvelle fonctionnalité a été introduite concernant la boucle for améliorée. En cela, l'index du tableau n'est pas nécessaire pour la récupération d'un élément du tableau.
int numArr[] = {
12,
14,
18,
16,
32
};
for (int n: numArr)
{
System.out.println("Result: " + n);
} 1.4.5- Pendant que.
Une boucle while doit respecter le format suivant.
while (expression)
{
statement;
} 1.4.6- Faire…While Loop
Une boucle do-while doit respecter le format suivant.
do
{
statement;
} while (expression); 1.4.7- Commutateur
Une instruction switch doit respecter le format suivant.
switch (expression)
{
case n:
statement;
break;
case x:
statement;
// Continue to default case.
default:
// Always add the default case.
statement;
break;
} 1.4.8- Essayer/Attraper/Enfin
L'instruction try/catch doit respecter le format suivant.
try
{
statement;
} catch (ExceptionClass e)
{
statement;
} Une instruction try-catch peut également être suivie de finally, qui s'exécute quel que soit le statut d'exécution.
finally
{
statement;
}
1.5- Commentaires
Voici les directives de codage Java pour des commentaires de qualité.
1- Utilisez des commentaires avant les déclarations d'interfaces, de classes, de fonctions membres et de champs. Adoptez le format Javadoc pour les commentaires.
2- Appliquez des commentaires de style C au code hiérarchique qui n'est plus applicable.
3- Limitez les commentaires à une seule ligne pour les fonctions membres, les sections de code et les déclarations de variables temporaires.
4- Rédigez des commentaires pour améliorer la clarté et la lisibilité du code.
5- N'ajoutez pas d'informations en double lorsque vous faites des commentaires.
6- Limitez la longueur du commentaire à 70 caractères par ligne.
En Java, il existe quatre façons d'ajouter des commentaires.
1.5.1- Bloquer les commentaires
Toutes les structures de données, les algorithmes de la fonction peuvent être expliqués à l'aide de commentaires de bloc. Les commentaires de bloc doivent être indentés au même niveau que le code.
/* * This is an example for Block Comments. * ... * ... */
1.5.2- Commentaires de fin
Principalement utilisé pour décrire le code de petite taille comme des conditions. Assurez-vous que le commentaire doit également être court.
if (javaVersion == newVersion) /* Special condition for version */
{
// code...
} 1.5.3- Commentaires sur une seule ligne
Utilisez ces commentaires dans les fonctions membres pour documenter la logique, les sections de code et les déclarations de variables temporaires. De plus, ce commentaire peut être utilisé pour indiquer la fin des instructions itératives lorsqu'elles sont imbriquées.
if (size > 1)
{
if (revision > 2)
{
// Sequence of statements
} // End of inner if statement
} // End of main if statement. 1.5.4- Commentaires sur la documentation
1- Les commentaires de la documentation décrivent les classes, les interfaces, les constructeurs, les méthodes et les champs Java.
2- Ce type de commentaires doit apparaître avant les déclarations.
3- Assurez-vous que ces commentaires ne se trouvent pas dans une méthode ou un bloc constructeur.
4- Les commentaires de documentation commencent par /** et se terminent par */.
5- JavaDoc traite les commentaires de documentation.
/**
* This Class Contains details about a blog post.
* It contains the number of words written and author of the post.
*
*/
Public class BlogPost {
int noOfWords;
char author[256];
};
1.6- Conventions de codage Java standard
1.6.1- Déclarations
1- Limitez une déclaration par ligne pour les objets et les variables.
2- Évitez de déclarer différents types d'une même ligne.
3- Définir les valeurs par défaut des variables locales au moment de la déclaration.
4- Le mieux est d'avoir toutes les déclarations au début du bloc.
5- N'utilisez pas de déclarations qui remplacent d'autres variables ayant des noms identiques.
6- Assurez-vous d'éliminer les avertissements s'il y en a.
1.6.2- Déclarations
1- N'écrivez qu'un seul énoncé par ligne.
2- N'initialisez pas plus de trois variables avec une virgule à l'intérieur d'une boucle "for".
3- N'oubliez pas de terminer un switch-case avec une instruction break.
4- Assurez-vous que l'instruction switch doit avoir une casse par défaut.
5- Ne câblez aucun nombre dans le code à la place, utilisez une macro pour définir des constantes.
6- Tout en comparant, gardez toujours la constante sur le côté gauche pour éviter toute affectation imprévisible.
7- En revenant d'une fonction, suivez l'approche de sortie unique et unique.
8- Prenez l'habitude de vérifier la valeur null lors de l'accès à n'importe quel objet ou structure de données.
9- Limitez le non. d'arguments à cinq pour les fonctions et les méthodes.
10- Aussi, ne prolongez pas le non. de caractères à partir de 80 caractères par ligne.
1.6.3- Déclaration d'importation
1- Commencez une déclaration d'importation à partir de la première colonne et utilisez un seul espace pour séparer le
2- Regroupez toutes les instructions d'importation en utilisant le nom du package.
3- Utilisez une ligne vide pour séparer les groupes d'instructions d'importation.
4- Triez les instructions d'importation selon l'ordre du dictionnaire.
5- Empêcher d'utiliser une instruction d'importation ouverte telle que
1.6.4- Espaces vides
1.6.4.1- Adopter les onglets de rejet d'espace vide
1- Définissez toujours un seul espace vide à utiliser dans l'éditeur. L'utilisation d'onglets n'est pas judicieuse car la taille des onglets varie d'un éditeur à l'autre.
2- Ajoutez un seul espace entre un mot-clé et la parenthèse ouvrante. Cela s'applique aux mots-clés tels que <catch, for, if, switch, synchronized et while> . Ne faites pas ça pour
if (obj instanceof Post) { // Correct.
if (obj instanceof(Post)) { // Incorrect. 3- Ajoutez un espace après la virgule dans une liste et après les points-virgules dans une boucle "for".
int num[5] = {10, 20, 30, 40, 50};
for (expr1; expr2; expr3) {
} 1.6.4.2- Éviter d'utiliser des blancs
1- Entre un nom de fonction et sa parenthèse ouvrante.
2- Avant ou après un "." opérateur (point).
3- Entre un opérateur unaire et son opérande.
4- Entre un casting et l'expression.
5- Après une parenthèse ouvrante ou avant une parenthèse fermante.
6- Après un crochet ouvrant "[" ou avant un crochet fermant "]".
// Pseudo code.
int test = arr1[x + y] + arr2[z];
test = (x + y) / (x * y);
if (((a + b) > (y - x)) || (x != (y + 3))) {
return dummy.area(x, y);
}
7- N'utilisez pas de caractères spéciaux comme les sauts de page ou les retours arrière.
1.6.5- Indentation
L'indentation de ligne est toujours de 4 espaces pour tous les niveaux d'indentation. Vous pouvez mettre en retrait à l'aide d'onglets (ce que vous devriez éviter) afin de réduire la taille du fichier. Cependant, vous ne devez pas modifier les paramètres de l'onglet physique pour y parvenir. Ils doivent comporter huit espaces.
1.6.6- Lignes de continuation
Les lignes doivent être limitées à 80 colonnes, sauf pour l'encodage non ASCII. S'ils dépassent 80 caractères, divisez-les en une ou plusieurs lignes de continuation. Toutes les lignes de continuation doivent être alignées et en retrait par rapport à la première ligne de la déclaration. Le niveau d'indentation dépend du type d'instruction. La même règle d'indentation que vous devez suivre pour les blocs imbriqués comme
// Correct.
long_function_name(long_expression1,
long_expression2,
long_expression3,
long_expression4);
// Correct - blank line follows continuation line because same indent
if (long_logical_test_1 || long_logical_test_2 ||
long_logical_test_3) {
statements;
}
// Incorrect.
while (long_expression1 || long_expression2 || long_expression3)
{
}
// Incorrect.
while (long_expression1 || long_expression2 ||
long_expression3) {
}
1.6.7- Commentaires sur la documentation des membres
1- Tout membre public doit être précédé d'un commentaire de documentation.
2- Le programmeur peut choisir d'ajouter une description pour les membres d'accès protégés et par défaut.
3- Les unités privées n'ont pas besoin d'un commentaire de documentation.
4- Les champs qui n'ont pas de commentaire de documentation doivent avoir des commentaires sur une seule ligne les décrivant.
1.6.8- Déclarations des champs de variable de classe et d'instance
1- Les variables définies à l'aide du mot-clé static sont des variables de classe.
2- Les variables définies sans le mot-clé "static" sont des variables d'instance.
3- Vous devez d'abord déclarer une variable de classe s'il y en a une.
4- Ensuite, vous devez déclarer une variable d'instance après la variable de classe.
Une déclaration de champ ressemble à ce qui suit. Les éléments entre crochets "[]" sont facultatifs.
[FieldModifiers] Type FieldName [= Initializer];
Les
public protected private static final transient volatile
Placez toutes les déclarations de champs sur des lignes séparées. Ne les matraquez pas les uns avec les autres sur une seule ligne.
static private int usageCount, index; // Incorrect static private int usageCount; // Correct static private long index; // Correct
1.7- Gestion des exceptions
Vous devez suivre les directives de codage Java ci-dessous pour implémenter une gestion efficace des exceptions.
1- Écrivez toujours un bloc catch pour gérer les exceptions.
2- Assurez-vous d'ajouter un message de journalisation ou la trace de la pile dans le bloc catch.
3- Évitez d'attraper l'exception générale et ayez une exception spécifique.
4- Le code de nettoyage doit être ajouté dans le
5- Cela fournit un emplacement unique pour le nettoyage, et son exécution est garantie.
1.8- Plugins Eclipse pour le style de code
Pour implémenter les directives de codage Java, vous avez besoin de plusieurs outils. Et il est facile de les intégrer à Eclipse IDE. Certains d'entre eux sont énumérés ci-dessous.
1- Plugin Checkstyle.
2- Outil de plug-in de vérification orthographique.
3- Plugin de recherche de bogues.
4- Outil de profileur de code – pour détecter la violation des directives.
5- TestNG ou JUnit pour les tests unitaires.
6- ANT/Maven pour la construction du projet.
Réflexion finale : consignes de codage Java
Nous avons essayé de couvrir les directives de codage Java les plus courantes qui, selon nous, pourraient être utiles à la fois aux développeurs Java et aux testeurs d'automatisation. Si vous souhaitez ajouter/mettre à jour ce message, n'hésitez pas à le partager avec nous.
Nos lecteurs donnent souvent leurs précieuses suggestions que nous apportons rapidement à travers de nouveaux articles sur ce blog. N'oubliez pas que votre intérêt nous pousse à fournir un meilleur contenu.
Meilleur,
TechBeamers
