Quelle est la différence entre
/**
* comment
*
*
*/
et
/*
*
* comment
*
*/
en Java? Quand dois-je les utiliser?
Réponses:
Le premier formulaire est appelé Javadoc . Vous l'utilisez lorsque vous écrivez des API formelles pour votre code, qui sont générées par l' javadocoutil. Par exemple, la page API Java 7 utilise Javadoc et a été générée par cet outil.
Certains éléments communs que vous verrez dans Javadoc incluent:
@param: ceci est utilisé pour indiquer quels paramètres sont passés à une méthode, et quelle valeur ils devraient 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: ceci est utilisé pour indiquer la première version de Java dans laquelle cette classe ou cette fonction était disponible
À titre d'exemple, voici Javadoc pour la compareméthode 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 deuxième forme est un commentaire en bloc (sur plusieurs lignes). Vous l'utilisez si vous souhaitez avoir plusieurs lignes dans un commentaire.
Je dirai que vous ne voudriez utiliser cette dernière forme qu'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.
Puisque Javadoc est le plus descriptif des deux, et que vous pouvez générer une documentation réelle suite à son utilisation, l'utilisation de Javadoc serait plus préférable à de simples commentaires de bloc.
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 ( // ...). Consultez la spécification du langage Java . Donc, pour le langage de programmation Java, les deux /* ... */et /** ... */sont des instances de commentaires traditionnels, et ils sont tous deux traités exactement 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 blancs).
Cependant, en tant que programmeur Java, vous n'utilisez pas seulement un compilateur Java. Vous utilisez une chaîne d'outils entière, 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, qui est inclus dans la plateforme Java et génère de la documentation. L'outil Javadoc analysera le fichier source Java et interprétera les parties intermédiaires /** ... */comme documentation.
Ceci est similaire aux balises comme FIXMEet TODO: si vous incluez un commentaire comme // TODO: fix thisou // FIXME: do that, la plupart des IDE mettront en évidence ces commentaires afin que vous ne les oubliez pas. Mais pour Java, ce ne sont que des commentaires.
javadocoutil ne peut pas interpréter quelque chose.
La lecture de la section 3.7 de JLS explique bien tout ce que vous devez savoir sur les commentaires en Java.
Il existe deux types de commentaires:
- /* texte */
Un commentaire traditionnel: tout le texte des caractères ASCII / * aux caractères ASCII * / est ignoré (comme en C et C ++).
- //texte
Un commentaire de fin de ligne: tout le texte des caractères ASCII // à la fin de la ligne est ignoré (comme en C ++).
À propos de votre question,
Le premier
/**
*
*/
est utilisé pour déclarer la technologie Javadoc .
Javadoc est un outil qui analyse les déclarations et les commentaires de documentation dans un ensemble de fichiers source et produit 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 API au format HTML. Les doclets peuvent également être utilisés pour effectuer des tâches spéciales non liées à la production de documentation API.
Pour plus d'informations, Docletreportez-vous à l' API .
Le second, comme expliqué clairement dans JLS, ignorera tout le texte entre /*et */est donc utilisé pour créer des commentaires multilignes.
Quelques autres choses que vous voudrez peut-être savoir sur les commentaires en Java
/* and */n'ont 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 /**.Ainsi, le texte suivant est un seul commentaire complet:
/* this comment /* // /** ends here: */
Je ne pense pas que les réponses existantes répondent adéquatement à cette partie de la question:
Quand dois-je les utiliser?
Si vous écrivez une API qui sera publiée ou réutilisée dans votre organisation, vous devez écrire des commentaires Javadoc complets pour chaque publicclasse, méthode et champ, ainsi que pour les protectedméthodes et les champs des non- finalclasses. Javadoc doit couvrir tout ce qui ne peut pas être véhiculé par la signature de méthode, comme les conditions préalables, les postconditions, 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é qui tue" de Javadoc est qu'il est étroitement intégré à Eclipse et à d'autres IDE. Un développeur n'a besoin que de placer le pointeur de sa souris sur un identifiant pour apprendre tout ce qu'il doit savoir à ce sujet. Se référer constamment à la documentation devient une seconde nature pour les développeurs Java expérimentés, 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 */
Cela indique un commentaire de documentation (commentaire doc, 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 doc lors de la préparation de la documentation générée automatiquement.
// text
Le compilateur ignore tout de //jusqu'à la fin de la ligne.
Maintenant, concernant le moment où vous devriez les utiliser:
À utiliser // textlorsque vous souhaitez commenter une seule ligne de code.
À utiliser /* text */lorsque vous souhaitez commenter plusieurs lignes de code.
À utiliser /** 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.
Le premier est pour Javadoc que vous définissez en haut des classes, interfaces, méthodes, etc. Vous pouvez utiliser Javadoc comme son nom l'indique pour documenter votre code sur ce que fait la classe ou quelle méthode fait, etc. et générer un rapport dessus.
Le deuxième est le commentaire du bloc de code. Disons, par exemple, que vous avez un bloc de code que vous ne voulez pas que le compilateur interprète, puis vous utilisez un commentaire de bloc de code.
un autre est // celui-ci que vous utilisez au niveau de l'instruction pour spécifier ce que les lignes de code suivantes sont censées faire.
Il y en a d'autres 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
Java prend en charge deux types de commentaires:
/* multiline comment */: Le compilateur ignore tout de /*à */. Le commentaire peut s'étendre sur plusieurs lignes.
// single line: Le compilateur ignore tout de //jusqu'à la fin de la ligne.
Certains outils tels que javadoc utilisent un commentaire multiligne spécial à leur fin. Par exemple, /** doc comment */un commentaire de documentation est utilisé par javadoc lors de la préparation de la documentation générée automatiquement, mais pour Java, il s'agit d'un simple commentaire multiligne.
/** .. */est juste un commentaire multiligne régulier, et le premier caractère à l'intérieur se trouve être un astérisque.