Commentaires Java

Les commentaires font partie d'un programme qui n'est pas exécuté. Le compilateur ignore simplement les commentaires car ils ne lui sont pas destinés. Ils sont rédigés en langage « humain » et sont destinés à expliquer le programme, une partie du programme, une seule ligne ou une méthode pour les développeurs ou les personnes impliquées dans le développement. Le plus souvent, les commentaires sont rédigés en anglais, c'est un peu une tradition. Dans cet article, nous allons parler des commentaires en Java et comment les utiliser correctement pour faciliter la vie de vous et de vos coéquipiers.

Commentaires Java : pourquoi ils sont importants

Ils disent que les programmeurs sont extrêmement paresseux lorsqu’il s’agit de commenter leur propre code. Cependant, il s'agit d'une compétence très importante, alors ne la sous-estimez pas, même si vous commencez tout juste à apprendre Java. Un code bien commenté a bien plus de valeur qu’un code sans commentaires car un tel programme est beaucoup plus facile à maintenir. Étant donné que les grands projets sont le plus souvent écrits en Java, des commentaires compétents accélèrent également le développement, car il est plus facile pour un programmeur de gérer le code des autres. Des commentaires sont nécessaires pour :

Comprenez le code. Le vôtre ou celui de quelqu'un d'autre. S'il vous semble que vous n'avez pas besoin de déchiffrer votre propre code parce que vous l'avez écrit, essayez d'ouvrir un programme relativement complexe que vous avez écrit il y a un mois ou même plus tôt et comprenez rapidement quoi, où et pourquoi vous aviez en tête. Les commentaires peuvent être utilisés pour expliquer la logique d'un programme ou d'un bloc de programme, ainsi que pour laisser des recommandations à ceux qui travailleront plus tard avec votre code. Ce type de commentaire peut être qualifié d’explicatif.
Contenant des informations sur l'objectif des objets, les paramètres d'entrée et de sortie (le cas échéant), des données sur le développeur et d'autres éléments importants liés au fragment de code. Ces commentaires se trouvent dans les en-têtes des modules, bibliothèques, procédures et fonctions. Ils peuvent être appelés commentaires de documentation.
Contrôlez les bugs et améliorez le code. Le code douteux ou le code qui doit être amélioré peut toujours être commenté et revisité ultérieurement. Si vous pensez qu'un certain problème peut être résolu d'une manière différente, mais que vous n'avez plus le temps pour cela, écrivez cette idée dans le commentaire. Sinon, très probablement, sous la pression d'un nouveau code, vous l'oublierez.

Types de commentaires en Java

Malgré le fait que vous puissiez écrire n'importe quoi et n'importe quoi dans les commentaires, il existe certains types de commentaires en Java et des règles pour les utiliser. En Java, les commentaires sont froids :

Commentaires sur une seule ligne
Commentaires sur plusieurs lignes
Commentaires sur la documentation

Commentaires sur une seule ligne

Les commentaires Java les plus courants sont des commentaires sur une seule ligne. Pour indiquer un tel commentaire, il suffit de mettre une double barre oblique avant le texte // . Les commentaires sur une seule ligne sont signalés uniquement au début du commentaire. Le commentaire continue jusqu'au bout de la ligne. Syntaxe:

//here is a single line comment.

Prenons un exemple de ce type de commentaires Java :

public class CommentsDemo1 {
   public static void main(String[] args) {
       System.out.println("This text is visible for Java compiler");
       //this text is single line comment
//This one is also single line comment
//they both (and me) are invisible for compiler
   }
}

Le résultat est :

Ce texte est visible pour le compilateur Java

Habituellement, un commentaire sur une seule ligne est situé au-dessus ou au-dessous de l'endroit commenté dans le programme, parfois sur la même ligne. Il est important que ce à quoi le commentaire fait référence soit visuellement clair.

Commentaires sur plusieurs lignes

Parfois, une ligne ne suffit pas pour écrire un commentaire Java. Par exemple, vous devez décrire le fonctionnement d’une méthode ou une formule complexe que vous mettez en œuvre. Dans ce cas, vous pouvez écrire plusieurs commentaires sur une seule ligne, mais il serait plus rationnel d'écrire des commentaires dits sur plusieurs lignes. Ils sont marqués des deux côtés avec les symboles /* */ . Syntaxe des commentaires multilignes :

/*This comment
is
Multi line comment
we can describe here
what we need */

Prenons un exemple de commentaires multilignes dans le code

public class RleTest {

   /*
   Run Length Encoding (RLE),  a data compression algorithm
   that replaces repeated characters (series)
   with one character and the number of its repetitions.

   this method is to decode a String using run-length encoding

    */
   private static String decodeRle(String encoded) {
       if (encoded.isBlank()) return "";
       StringBuilder result = new StringBuilder();
       int count = 0;
       char baseChar = encoded.charAt(0);
       for (int i = 1; i <= encoded.length(); i++) {
           char c = i == encoded.length() ? '$' : encoded.charAt(i);
           if (Character.isDigit(c)) {
               count = count * 10 + Character.digit(c, 10);
           } else {
               do {
                   result.append(baseChar);
                   count--;
               } while (count > 0);
               count = 0;
               baseChar = c;
           }
       }
       return result.toString();
   }
   public static void main(String[] args) {
       System.out.println(decodeRle("C3ecddf8"));
   }
}

Commentaires sur la documentation Java

Il s'agit d'un type spécial de commentaires Java utilisé pour générer une page de documentation. Habituellement, les développeurs rédigent des commentaires sur la documentation à l'aide de Javadoc, un générateur de documentation permettant de générer de la documentation API au format HTML à partir du code source Java. Le format des documents utilisé par Javadoc est la norme de l'industrie pour la documentation des classes Java et les IDE les plus populaires tels qu'IntelliJ IDEA et Eclipse génèrent automatiquement du HTML Javadoc. Les commentaires de la documentation Java ont la syntaxe ci-dessous :

/**
Some important Javadoc comments here
You don’t know it yet, but Javadoc rulez

@author  Java Developer
*/

Voici un exemple : c'est un fragment de la classe Java Short . À propos, vous pouvez consulter n'importe quel code de classe Java à partir de votre IDE (par exemple dans IntelliJ IDEA à partir de Windows, appuyez simplement sur ctrl+LBM ou ctrl + b (sous Windows) sur le nom de n'importe quelle classe ou méthode).

package java.lang;

import jdk.internal.HotSpotIntrinsicCandidate;
import jdk.internal.misc.VM;

/**
* The {@code Short} class wraps a value of primitive type {@code
* short} in an object.  An object of type {@code Short} contains a
* single field whose type is {@code short}.
*
* <p>In addition, this class provides several methods for converting
* a {@code short} to a {@code String} and a {@code String} to a
* {@code short}, as well as other constants and methods useful when
* dealing with a {@code short}.
*
* @author  Nakul Saraiya
* @author  Joseph D. Darcy
* @see     java.lang.Number
* @since   1.1
*/
public final class Short extends Number implements Comparable<Short> {

   /**
    * A constant holding the minimum value a {@code short} can
    * have, -2<sup>15</sup>.
    */
   public static final short   MIN_VALUE = -32768;

   /**
    * A constant holding the maximum value a {@code short} can
    * have, 2<sup>15</sup>-1.
    */
   public static final short   MAX_VALUE = 32767;

   /**
    * The {@code Class} instance representing the primitive type
    * {@code short}.
    */
   @SuppressWarnings("unchecked")

Voici le code Java de la méthode println() bien connue et appréciée de tous les débutants avec le commentaire suivant :

/**
* Prints a String and then terminate the line.  This method behaves as
* though it invokes {@link #print(String)} and then
* {@link #println()}.
*
* @param x  The {@code String} to be printed.
*/
public void println(String x) {
   if (getClass() == PrintStream.class) {
       writeln(String.valueOf(x));
   } else {
       synchronized (this) {
           print(x);
           newLine();
       }
   }
}

Javadoc possède des balises Javadoc spéciales marquées d'un @ que vous pouvez voir dans le code ci-dessus. L'exemple d'une telle balise Javadoc est @author qui ajoute le nom de l'auteur de la classe. Une autre balise Javadoc est @puisqu'elle ajoute un commentaire indiquant que cette classe est utilisée depuis la version spécifiée de Java. Rédiger de bons documents Javadoc nécessite des connaissances et de l'expérience (et de la patience !). Vous pouvez trouver plus d'informations sur Javadoc dans la documentation officielle Comment rédiger des commentaires de doc pour l'outil Javadoc .

PS quelques exemples de commentaires amusants tirés de la vraie vie

/**
*Dear Maintainer
*
*Once you are done trying to 'optimize' this routine,
*and you have realized what a terrible mistake that was,
*please increment the following counter as a warning
*to the next guy.
*
*total_hours_wasted_here = 73
*/

Exception up = new Exception("Something is really wrong.");
throw up;  //ha ha

// When I wrote this, only God and I understood what I was doing
// Now, God only knows

// sometimes I believe compiler ignores all my comments

/**
Always returns true.
*/
public boolean isAvailable() {
return false;
}

Pour renforcer ce que vous avez appris, nous vous proposons de regarder une leçon vidéo de notre cours Java