Règles Java pour les identifiants

Les règles suivantes s’appliquent quand vous choisissiez des noms pour les classes, les méthodes, les variables et les constantes dans Java. Le programme plantera si ces règles ne sont pas respectées:

• Caractères permis : L’identifiant est composé uniquement des caractères a-z, A-Z, 0-9, _ et $. Notez qu’il n’y a pas d’espaces dans cette liste. Les lettres avec accents sont aussi acceptés, mais à cause de la complexité des différents encodages de caractères, il est préférable de les éviter.
• Les majuscules et les minuscules font une différence : Les identifiants sont sensibles à la casse. Le même mot écrit avec des majuscules ou des minuscules fait référence à deux identifiants distincts.
• Aucun chiffre au début : Les identifiants ne peuvent pas commencer par un chiffre.
• Pas un mot clé : Les identifiants ne peuvent pas être des mots-clés Java, p. ex. public, class, void, int, for, if, etc. Ces mots sont déjà définis par Java et ne peuvent pas être utilisés pour autre chose.

Conventions Java pour les identifiants

Différents langages encouragent différents styles de noms pour les identifiants pour les différents élements du programme. Cela aide les développeurs à associer une fonction à un identifiant simplement en observant sa forme.

Voici les conventions de Java.

Casse chameau pour les méthodes et les variables

Tous les noms de variables et de méthodes respectent la casse chameau (“camel case” en anglais) : toutes les lettres sont minuscules et chaque mot suivant commence par une majuscule. Par exemple : nomDeVariable, nomDeMethode().

Pourquoi le nom chameau? Parce que les majuscules au milieu des mots ressemblent aux bosses sur le dos d’un chameau.

Casse pascal pour les classes et les noms de fichiers

La casse pascal et comme la casse chameau, mais la première lettre est aussi une majuscule. Par exemple : NomDeClasse.

C’est vraiment important d’écrire les noms de classe avec une majuscule initiale pour les distinguer des variables et des méthodes. C’est une convention de nommage très répandue même au-delà de Java.

Pourquoi le nom pascal? C’est un hommage à Pascal, un langage de programmation historiquement important qui utilisait cette convention.

En Java, le nom du fichier doit avoir le même nom que la classe qu’il contient. Si la classe s’appelle NomDeClasse, le fichier doit s’appeler NomDeClasse.java. Ainsi, tous les noms de fichiers seront également en casse pascal. Dans notre cas, où la déclaration de la classe sera implicite, il faut tout de même nommer le fichier avec la casse pascal parce que le fichier et la classe sont liés.

Casse serpent avec majuscules pour les constantes

Pour indiquer qu’une variable ne change jamais de valeur, soit qu’elle est constante, on utilise une casse spéciale. Les constantes sont écrites en majuscules avec des soulignements pour séparer les mots. Par exemple : NOM_DE_CONSTANTE.

Pourquoi le nom serpent? Possiblement parce qu’en chaînant les mots avec des soulignements, on imagine les segments du corps d’un serpent. Possiblement parce que les soulignement ressemblent à des serpents au sol. Le nom n’est pas officiel, mais il est communément utilisé depuis au moins 2004.

Résumé des conventions

Identifiants descriptifs

Si les conventions aident les développeurs à reconnaître la fonction générale d’un identifiant, les mots utilisés dans l’identifiant les aident à comprendre plus spécifiquement ce que l’identifiant représente dans le programme.

C’est extrêmement important de choisir des noms descriptifs pour tous les identifiants tant pour vous aider à comprendre le sens de ce que vous tentez d’accomplir que pour communiquer ce sens aux autres développeurs.

Cela s’applique pour tous les langages de programmation.

Exemple

Que veux dire l’expression suivante?

a = b * c;

À part savoir qu’on assigne le produit de deux valeurs à une troisième valeur, c’est impossible de le savoir.

Maintenant, que veux dire l’expression suivante?

areaOfRectangle = length * width;

ou

weeklyPay = hoursWorked * hourlyRate;

Ces deux expressions on exactement la même forme que le premier exemple, mais on peut savoir pourquoi on l’a utilisé dans chaque cas. C’est parce que les identifiants ont été nommés de manière descriptive.

Note : même si on travaille en français, il est préférable d’utiliser l’anglais pour les identifiants parce que les mots-clés du langage sont en anglais. Ainsi, le code est plus facile à lire et on évite les problèmes de caractères spéciaux (p. ex. é, ç, à, etc.).

Commentaires explicatifs - commentaires de ligne ou de bloc

Parfois simplement respecter les conventions de nommage et la pratique de noms descriptifs, il ne reste pas grande chose à expliquer dans le code. Mais il y a des moments où un commentaire est nécessaire pour expliquer un choix de variable ou un algorithme particulier. C’est là que les commentaires explicatifs ont leur place.

Les commentaires sont ignorés par le compilateur, donc ils n’ont pas d’impact sur le fonctionnement du programme. Ainsi, on devrait les écrire en français dans un langage naturel qui nous convient.

C’est un art de trouver à quel point les commentaires explicatifs passent d’utile à redondant. Lorsqu’il y a trop de commentaires ou les commentaires dupliquent l’information dans les identifiants descriptifs, ils nuisent à la clarté du code. En contrepartie, s’il n’y a pas assez de commentaires, la logique de certaines parties du code peut être difficile à suivre. EN CAS DE DOUTE, surtout comme novice, il vaut mieux en mettre un peu trop que pas assez.

Syntaxe des commentaires

Il y a deux façons de laisser des commentaires dans le code Java :

• Les commentaires de ligne suivent deux barres obliques // et se limitent à la ligne sur laquelle ils sont écrits.
• Les commentaires de bloc s’étendent entre les délimiteurs /* et */ ce qui leur permet de couvrir plusieurs lignes, au besoin.

Exemple de commentaire de ligne

On suit souvent la déclaration d’une variable avec un commentaire de ligne pour expliquer pourquoi on a choisi une valeur initiale particulière ou pour indiquer comment il sera utilisé plus loin, si ce n’est pas déjà assez clair par le nom de la variable.

int age; // conservera l'âge fourni par l'utilisateur

Si on arrive à une structure de contrôle (comme une sélection ou une boucle), on précède souvent la structure avec un commentaire pour expliquer le but de la structure. Si l’explication est courte, ce commentaire peut-être un commentaire de ligne.

// Décider si l'utilisateur peut voter
if (age > 18) {
    System.out.println("Vous pouvez voter!");
} else {
    System.out.println("Vous ne pouvez pas voter.");
}

Finalement, certaines opérations complexes peuvent être expliquées avec un commentaire de ligne.

// La distance entre deux points (x1, y1) et (x2, y2)
int dx = x2 - x1;
int dy = y2 - y1;
double distance = Math.sqrt(dx * dx + dy * dy);

Exemple de commentaire de bloc

Le commentaire de bloc est utilisé comme en-tête d’un fichier, pour présenter des informations comme la description, comment l’utiliser, qui l’a fait, s’il y a une licence spécifique attachée au code, etc.

/*
Nom de la classe : Salut
Description : Un programme simple qui affiche un message de salutation.
Auteur : David Crowley
Date de création : 2023-09-01
*/

On utilise aussi un commentaire de bloc si la logique d’un algorithme ne peut pas s’expliquer sur une seule ligne.

/*
On gagne si on atteint 100 points ou plus.
On perd si on atteint 20 tentatives.
On quitte en milieu du jeu si l'utilisateur a tapé "q".
*/
if (points >= 100) {
    System.out.println("Vous avez gagné!");
} else if (attempts >= 20) {
    System.out.println("Vous avez perdu.");
} else if (userInput.equals("q")) {
    System.out.println("Vous avez quitté le jeu.");
}

Notez que vous pouvez aussi utiliser plusieurs commentaires de ligne une après l’autre au lieu d’utiliser un commentaire de bloc. C’est ce qui arrive souvent, parce qu’on ne réalise pas la longueur du commentaire avant de l’écrire.

Documentation interne - Javadoc

Ceci est un sujet qui est plus avancé. Nous l’utiliserons pas dès le début, contrairement aux autres sujets de cette leçon. La section demeure ici pour référence future.

Les commentaires explicatifs sont utiles pour présenter notre logique lorsqu’un développeur lit les détails internes de notre code. Mais c’est aussi pratique de connaître le contenu d’une classe ou la structure d’une méthode même sans lire le code. C’est là que la documentation interne entre en jeu.

La documentation interne, appelé javadoc en Java, est un format de commentaire spécial qui est reconnu par les outils Java pour générer de la documentation officielle. Les outils Java vous affichent le contenu de ces commentaires dans l’auto-complétion (lorsque vous tapez votre code) et dans les info-bulles (lorsque votre souris passe sur un identifiant).

Pour créer un commentaire javadoc :

• on utilise un commentaire de bloc avec un * supplémentaire au début. Le bloc commence alors par /** (deux astérisques) et se termine par */.
• Le javadoc doit être placé immédiatement devant la déclaration de la classe ou de la méthode qu’il documente. Sinon, les outils Java ne sauront pas à quoi il se réfère : il sera considéré comme un simple commentaire de bloc.
• C’est mieux d’écrire le javadoc après avoir écrit le code. Les outils de votre EDI peuvent alors ajouter plusieurs détails automatiquement avec le bon format, vous laissant juste la tâche d’ajouter les descriptions.
• Votre EDI ajoutera probablement des * supplémentaires pour chaque ligne du javadoc. C’est une convention pour rendre le commentaire plus lisible, mais ces astérisques internes ne sont pas nécessaires pour que le javadoc fonctionne.

Format général pour le javadoc d’une méthode

Les paramètres (les @param) et la valeur de retour (le @return) sont des sujets plus avancés qui seront traités plus tard dans le cours. Pour l’instant, si on demande le javadoc d’une méthode, on s’attend à voir juste sa description.

/**
 * Description de la méthode.
 *
 * @param nomParamètre Description du paramètre
 * @param nomAutreParamètre Description de l'autre paramètre
 * @return Description de la valeur de retour
 */