Utilisation des commentaires 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 le code source, tels 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.

Pourquoi utiliser les commentaires 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.

Influent-ils sur le fonctionnement du programme?

Les commentaires d'implémentation en code Java ne sont accessibles qu'aux humains. Les compilateurs Java ne se soucient pas d'eux et lors de la compilation du programme, ils les ignorent simplement. La taille et l'efficacité de votre programme compilé ne seront pas affectées par le nombre de commentaires dans votre code source.

Commentaires sur la mise en œuvre

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 * /
```

Commentaires Javadoc

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

les fichiers source sont inclus dans la syntaxe de début et de fin comme ceci:

/ **

* /

. Chaque commentaire dans ces derniers est précédé d'un

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ésumant votre classe.
* Voici une autre ligne.
* /
Publique classe Ma classe

…

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

@param

La balise définit les paramètres d'une méthode:

 / ** méthode principale
* @param args String []
* /
Publique statique né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.

Conseils d'utilisation des commentaires

Ne pas trop commenter. Il n'est pas nécessaire d'expliquer chaque ligne de votre programme. Si votre programme se déroule logiquement et que rien d'inattendu ne se produit, ne ressentez pas le besoin d'ajouter un commentaire.
Mettre 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
* /

Science