/ ** et / * dans Java Commentaires
Quelle est la différence entre
/**
* comment
*
*
*/
et
/*
*
* comment
*
*/
en Java? Quand devrais-je les utiliser?
Le premier formulaire s'appelle Javadoc . Vous l'utilisez lorsque vous écrivez des API formelles pour votre code, générées par l'outil javadoc. Par exemple, la page de l'API Java 7 utilise Javadoc et a été généré par cet outil.
Certains éléments communs que vous verriez dans Javadoc incluent:
@param: Ceci est utilisé pour indiquer quels paramètres sont passés à une méthode et quelle valeur ils sont supposés avoir.@return: ceci est utilisé pour indiquer le résultat que la méthode va rendre@throws: ceci est utilisé pour indiquer qu'une méthode lève une exception ou une erreur en cas de certaines entrées@since: il est utilisé pour indiquer la version la plus ancienne de Java dans laquelle cette classe ou fonction était disponible
À titre d'exemple, voici Javadoc pour la méthode compare de Integer:
/**
* Compares two {@code int} values numerically.
* The value returned is identical to what would be returned by:
* <pre>
* Integer.valueOf(x).compareTo(Integer.valueOf(y))
* </pre>
*
* @param x the first {@code int} to compare
* @param y the second {@code int} to compare
* @return the value {@code 0} if {@code x == y};
* a value less than {@code 0} if {@code x < y}; and
* a value greater than {@code 0} if {@code x > y}
* @since 1.7
*/
public static int compare(int x, int y) {
return (x < y) ? -1 : ((x == y) ? 0 : 1);
}
La seconde forme est un commentaire de bloc (multi-lignes). Vous l'utilisez si vous voulez avoir plusieurs lignes dans un commentaire.
Je dirai que vous ne voudriez utiliser que la dernière forme avec parcimonie ; Autrement dit, vous ne voulez pas surcharger votre code avec des commentaires de bloc qui ne décrivent pas les comportements que la méthode/fonction complexe est censée avoir.
Comme Javadoc est le plus descriptif des deux et que vous pouvez générer de la documentation à la suite de son utilisation, l’utilisation de Javadoc serait préférable à un simple blocage de commentaires.
Pour le langage de programmation Java , il n'y a aucune différence entre les deux. Java a deux types de commentaires: les commentaires traditionnels (/* ... */) et les commentaires de fin de ligne (// ...). Voir le Spécification du langage Java . Ainsi, pour le langage de programmation Java, /* ... */ et /** ... */ sont des occurrences de commentaires traditionnels et sont tous les deux traités de la même manière par le compilateur Java. , c’est-à-dire qu’ils sont ignorés (ou plus correctement: ils sont traités comme des espaces).
Cependant, en tant que programmeur Java, vous n'utilisez pas uniquement un compilateur Java. Vous utilisez une chaîne d'outils complète, qui comprend, par exemple, le compilateur, un IDE, un système de construction, etc. Et certains de ces outils interprètent les choses différemment du compilateur Java. En particulier, les commentaires /** ... */ sont interprétés par l'outil Javadoc, inclus dans la plate-forme Java , et génère de la documentation. . L'outil Javadoc analysera le fichier source Java et interprétera les parties entre /** ... */ comme documentation.
Ceci est similaire aux balises telles que FIXME et TODO: si vous incluez un commentaire tel que // TODO: fix this ou // FIXME: do that, la plupart des IDE mettront en surbrillance ces commentaires afin de ne pas oublier leur. Mais pour Java, ce ne sont que des commentaires.
Le premier est les commentaires Javadoc. Ils peuvent être traités par l’outil javadoc pour générer la documentation de l’API pour vos classes. La seconde est un commentaire de bloc normal.
En lisant la section .7 of JLS , expliquez bien tout ce que vous devez savoir sur les commentaires en Java.
Il y a deux sortes de commentaires:
- /* texte */
Un commentaire traditionnel: tout le texte des ASCII caractères/* au ASCII caractères */est ignoré (comme en C et C++).
- //texte
Commentaire de fin de ligne: tout le texte des caractères ASCII jusqu'à la fin de la ligne est ignoré (comme en C++).
À propos de votre question,
Le premier
/**
*
*/
est utilisé pour déclarer Javadoc Technology .
Javadoc est un outil qui analyse les déclarations et les commentaires de la documentation dans un ensemble de fichiers source et génère un ensemble de pages HTML décrivant les classes, les interfaces, les constructeurs, les méthodes et les champs. Vous pouvez utiliser un doclet Javadoc pour personnaliser la sortie Javadoc. Un doclet est un programme écrit avec l'API Doclet qui spécifie le contenu et le format de la sortie à générer par l'outil. Vous pouvez écrire un doclet pour générer tout type de sortie de fichier texte, tel que HTML, SGML, XML, RTF et MIF. Oracle fournit un doclet standard pour générer une documentation d'API au format HTML. Les doclets peuvent également être utilisés pour effectuer des tâches spéciales non liées à la production de la documentation API.
Pour plus d'informations sur Doclet, reportez-vous à API .
Le second, comme expliqué clairement dans JLS, ignorera tout le texte entre /* et */ et servira donc à créer des commentaires multilignes.
Quelques autres choses à savoir sur les commentaires en Java
- Les commentaires ne s'emboîtent pas.
/* and */n'a pas de signification particulière dans les commentaires commençant par//.//n'a pas de signification particulière dans les commentaires commençant par/* or /**.- La grammaire lexicale implique que les commentaires ne figurent pas dans les littéraux de caractère ( §3.10.4 ) ni dans les littéraux de chaîne ( §3.10.5 ).
Ainsi, le texte suivant est un seul commentaire complet:
/* this comment /* // /** ends here: */
Je ne pense pas que les réponses existantes répondent de manière adéquate à cette partie de la question:
Quand devrais-je les utiliser?
Si vous écrivez une API qui sera publiée ou réutilisée au sein de votre organisation, vous devez écrire des commentaires Javadoc complets pour chaque classe, méthode et champ public, ainsi que pour les méthodes et champs protected. -final classes. Javadoc doit couvrir tout ce qui ne peut pas être véhiculé par la signature de la méthode, tel que les conditions préalables, les conditions ultérieures, les arguments valides, les exceptions d'exécution, les appels internes, etc.
Si vous écrivez une API interne (utilisée par différentes parties du même programme), Javadoc est sans doute moins important. Mais pour le bénéfice des programmeurs de maintenance, vous devez toujours écrire Javadoc pour toute méthode ou champ où l'utilisation ou la signification correcte n'est pas immédiatement évidente.
La fonctionnalité "killer" de Javadoc réside dans le fait qu’elle est étroitement intégrée à Eclipse et à d’autres IDE. Un développeur n'a qu'à survoler son identifiant avec la souris sur son identifiant pour apprendre tout ce dont il a besoin. Faire constamment référence à la documentation devient une seconde nature pour les développeurs expérimentés Java, ce qui améliore la qualité de leur propre code. Si votre API n'est pas documentée avec Javadoc, les développeurs expérimentés ne voudront pas l'utiliser.
Les commentaires dans la liste suivante de Java Code sont les caractères grisés:
/**
* The HelloWorldApp class implements an application that
* simply displays "Hello World!" to the standard output.
*/
class HelloWorldApp {
public static void main(String[] args) {
System.out.println("Hello World!"); //Display the string.
}
}
Le langage Java prend en charge trois types de commentaires:
/* text */
Le compilateur ignore tout de /* à */.
/** documentation */
Ceci indique un commentaire de documentation (doc comment, pour faire court). Le compilateur ignore ce type de commentaire, tout comme il ignore les commentaires qui utilisent /* et */. L'outil javadoc JDK utilise les commentaires de la documentation lors de la préparation de la documentation générée automatiquement.
// text
Le compilateur ignore tout de // à la fin de la ligne.
Maintenant en ce qui concerne le moment où vous devriez les utiliser:
Utilisez // text lorsque vous souhaitez commenter une seule ligne de code.
Utilisez /* text */ lorsque vous souhaitez commenter plusieurs lignes de code.
Utilisez /** documentation */ lorsque vous souhaitez ajouter des informations sur le programme pouvant être utilisées pour la génération automatique de la documentation du programme.
La première est pour Javadoc que vous définissez en haut des classes, interfaces, méthodes, etc. Vous pouvez utiliser Javadoc comme son nom le suggère pour documenter votre code sur ce que fait la classe ou quelle méthode, etc., et générer un rapport dessus.
Le second est le commentaire de bloc de code. Disons par exemple que vous avez un bloc de code que vous ne voulez pas que le compilateur interprète, alors vous utilisez un commentaire de bloc de code.
un autre exemple est // ceci que vous utilisez au niveau de l'instruction pour spécifier ce que les lignes de code précédentes sont censées faire.
Il y en a d'autres aussi comme // TODO, cela marquera que vous voulez faire quelque chose plus tard à cet endroit
// FIXME vous pouvez utiliser lorsque vous avez une solution temporaire mais que vous souhaitez visiter plus tard et l'améliorer.
J'espère que cela t'aides
- Commentaire unique, par exemple: // commentaire
- Commentaire sur plusieurs lignes, par exemple:/* commentaire * /
- commentaire javadoc, par exemple:/** commentaire * /