Comment utiliser les commentaires dans le code Java

Les commentaires Java sont des notes dans un fichier de code Java qui sont ignorées par le compilateur et le moteur d'exécution. Ils sont utilisés pour annoter le code afin de clarifier sa conception et son objectif. Vous pouvez ajouter un nombre illimité de commentaires à un fichier Java, mais il existe certaines "meilleures pratiques" à suivre lors de l'utilisation des commentaires.

Généralement, les commentaires de code sont des commentaires d '"implémentation" qui expliquent code source, telles que les descriptions des classes, des interfaces, des méthodes et des champs. Ce sont généralement quelques lignes écrites au-dessus ou à côté du code Java pour clarifier ce qu'il fait.

Un autre type de commentaire Java est un commentaire Javadoc. Les commentaires Javadoc diffèrent légèrement dans la syntaxe des commentaires d'implémentation et sont utilisés par le programme javadoc.exe pour générer la documentation HTML Java.

Il est recommandé de prendre l'habitude de mettre des commentaires Java dans votre code source pour améliorer sa lisibilité et sa clarté pour vous-même et les autres programmeurs. Il n'est pas toujours clair instantanément ce qu'une section de code Java effectue. Quelques lignes explicatives peuvent réduire considérablement le temps nécessaire pour comprendre le code.

Commentaires sur la mise en œuvre dans Code Java ne sont là que pour les humains à lire. Les compilateurs Java ne se soucient pas d'eux et quand compilation du programme, ils les sautent simplement. La taille et l'efficacité de votre programme compilé ne seront pas affectées par le nombre de commentaires dans votre code source.

Les commentaires sur la mise en œuvre se présentent sous deux formats différents:

• Commentaires sur la ligne: Pour un commentaire d'une ligne, tapez "//" et suivez les deux barres obliques avec votre commentaire. Par exemple:

   // c'est un commentaire sur une seule ligne
  int guessNumber = (int) (Math.random () * 10); 

  Lorsque le compilateur rencontre les deux barres obliques, il sait que tout ce qui se trouve à droite doit être considéré comme un commentaire. Ceci est utile lors du débogage d'un morceau de code. Ajoutez simplement un commentaire à partir d'une ligne de code que vous déboguez et le compilateur ne le verra pas:

  •  // c'est un commentaire sur une seule ligne
    // int guessNumber = (int) (Math.random () * 10); 

    Vous pouvez également utiliser les deux barres obliques pour faire un commentaire de fin de ligne:

  •  // c'est un commentaire sur une seule ligne
    int guessNumber = (int) (Math.random () * 10); // Un commentaire de fin de ligne 

• Bloquer les commentaires: Pour démarrer un commentaire de bloc, tapez "/ *". Tout ce qui se trouve entre la barre oblique et l'astérisque, même s'il se trouve sur une ligne différente, est traité comme un commentaire jusqu'à ce que les caractères "* /" terminent le commentaire. Par exemple:

   /* cette 
  est 
  une
  bloquer
  commentaire
  */
  / * il en est de même * /
  

Utilisez des commentaires Javadoc spéciaux pour documenter votre API Java. Javadoc est un outil inclus avec le JDK qui génère de la documentation HTML à partir des commentaires dans le code source.

Un commentaire Javadoc dans

.Java

/**

*/

*

Placez ces commentaires directement au-dessus de la méthode, de la classe, du constructeur ou de tout autre élément Java que vous souhaitez documenter. Par exemple:

// myClass.java
/**
* Faites-en une phrase récapitulative décrivant votre classe.
* Voici une autre ligne.
*/
Publiqueclasse Ma classe
{
...
}

Javadoc incorpore diverses balises qui contrôlent la façon dont la documentation est générée. Par exemple, le

@param

 / ** méthode principale
* @param args String []
*/​
Publiquestatiquenéant main (chaîne [] arguments)
​{
System.out.println ("Bonjour tout le monde!");
}

De nombreuses autres balises sont disponibles dans Javadoc, et il prend également en charge les balises HTML pour aider à contrôler la sortie. Consultez votre documentation Java pour plus de détails.

• Ne pas trop commenter. Il n'est pas nécessaire d'expliquer chaque ligne de votre programme. Si votre programme se déroule de manière logique et que rien d'inattendu ne se produit, ne ressentez pas le besoin d'ajouter un commentaire.
• Mettez en retrait vos commentaires. Si la ligne de code que vous commentez est indentée, assurez-vous que votre commentaire correspond à l'indentation.
• Gardez les commentaires pertinents. Certains programmeurs sont excellents pour modifier le code, mais pour une raison quelconque, oubliez de mettre à jour les commentaires. Si un commentaire ne s'applique plus, modifiez-le ou supprimez-le.
• Ne pas imbriquer les commentaires de bloc. Ce qui suit entraînera une erreur de compilation:

   /* cette 
  est
  / * Ce commentaire de bloc termine le premier commentaire * /
  une
  bloquer
  commentaire
  */