/ ** et / * dans les commentaires Java

Question 1

Quelle est la différence entre

/**
 * comment
 *
 *
 */

et

/*
 * 
 * comment
 *
 */

en Java? Quand dois-je les utiliser?

Question 2

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.

Question 3

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.

Question 4

Le premier concerne les commentaires Javadoc. Ils peuvent être traités par l' javadocoutil pour générer la documentation API de vos classes. Le second est un commentaire de bloc normal.

Question 5

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

Les commentaires ne s'imbriquent pas.
/* 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 /**.
La grammaire lexicale implique que les commentaires n'apparaissent pas dans des littéraux de caractères ( §3.10.4 ) ou des chaînes de caractères ( §3.10.5 ).

Ainsi, le texte suivant est un seul commentaire complet:

/* this comment /* // /** ends here: */

Question 6

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.

Question 7

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.

Question 8

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

Question 9

Commentaire unique par exemple: // commentaire
Commentaire sur plusieurs lignes, par exemple: / * commentaire * /
Commentaire javadoc par exemple: / ** commentaire * /

Question 10

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.

Answer 1

198

Quelle est la différence entre

/**
 * comment
 *
 *
 */

et

/*
 * 
 * comment
 *
 */

en Java? Quand dois-je les utiliser?

java comments javadoc Dev
la source

Answer 2

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.

Answer 3

35

Un autre avantage intéressant de l'utilisation de Javadoc au lieu de simples commentaires de bloc est que lorsque vous mettez un commentaire Javadoc avant un élément Java (par exemple, une signature de méthode, une déclaration de champ, une classe, etc.), cela active les IDE - du moins Eclipse pour sûr - pour afficher votre commentaire (par exemple dans une info-bulle) lorsque vous déplacez le curseur - ou survolez avec la souris - sur une référence à cet élément Java.

SantiBailors

Answer 4

Est-il acceptable d'utiliser les commentaires java doc pour les variables?

the_prole

Answer 5

@the_prole: Vous pouvez, mais je n'y vois pas beaucoup de valeur à moins que cela ne fasse partie d'un package de type Constants. Même dans ce cas, les commentaires en ligne ont été plus précieux dans mon expérience.

Makoto

Answer 6

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.

Answer 7

48

+1 pour avoir fait la distinction importante que la syntaxe Javadoc ne fait pas partie du langage, ce qu'aucune autre réponse n'a actuellement capturé.

Chris Hayes

Answer 8

1

C'est pourquoi vous pouvez avoir un projet qui se compile très bien dans Maven, mais dès que vous décidez de joindre des JavaDocs, il commence à se plaindre car l' javadocoutil ne peut pas interpréter quelque chose.

Captain Man

Answer 9

Le premier concerne les commentaires Javadoc. Ils peuvent être traités par l' javadocoutil pour générer la documentation API de vos classes. Le second est un commentaire de bloc normal.

Answer 10

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

Les commentaires ne s'imbriquent pas.
/* 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 /**.
La grammaire lexicale implique que les commentaires n'apparaissent pas dans des littéraux de caractères ( §3.10.4 ) ou des chaînes de caractères ( §3.10.5 ).

Ainsi, le texte suivant est un seul commentaire complet:

/* this comment /* // /** ends here: */

Answer 11

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.

Answer 12

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.

Answer 13

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

Answer 14

1

Commentaire unique par exemple: // commentaire
Commentaire sur plusieurs lignes, par exemple: / * commentaire * /
Commentaire javadoc par exemple: / ** commentaire * /

Ramlal S
la source

4

Cela n'ajoute rien aux réponses existantes.

shmosel

1

@shmosel non, cela les résume.

Dét.

Answer 15

4

Cela n'ajoute rien aux réponses existantes.

shmosel

Answer 16

1

@shmosel non, cela les résume.

Dét.

Answer 17

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.

Answer 18

12

Le langage Java ne prend en charge que deux types de commentaires. Un commentaire sous la forme de /** .. */est juste un commentaire multiligne régulier, et le premier caractère à l'intérieur se trouve être un astérisque.

Chris Hayes

/ ** et / * dans les commentaires Java

Réponses: