Je suis en train de développer un projet et je me pose une question :
Soit le prototype de méthode suivant :
/**
* getTableLangue renvoie le nom de la table Langue de l'id passé
en paramètre
* @param idLang
* @return le nom de la table Langue de l'id passé en paramètre
*/
public static String getTableLangue(byte idLangue){
...}
Je trouve que le commentaire est redondant par rapport au nom de la
méthode et qu'il n'apporte rien.
Je suis pour commenter mon code mais pour qu'il apporte qque chose.
Votre avis ?
Vous mettez quoi comme commentaire pour vos javadoc ?
Cette action est irreversible, confirmez la suppression du commentaire ?
Signaler le commentaire
Veuillez sélectionner un problème
Nudité
Violence
Harcèlement
Fraude
Vente illégale
Discours haineux
Terrorisme
Autre
trickyfox
Gabriel wrote in message news:<cg7n62$kd3$...
Bonjour,
Je suis en train de développer un projet et je me pose une question :
Soit le prototype de méthode suivant :
/** * getTableLangue renvoie le nom de la table Langue de l'id passé en paramètre * @param idLang * @return le nom de la table Langue de l'id passé en paramètre */ public static String getTableLangue(byte idLangue){ ...}
Je trouve que le commentaire est redondant par rapport au nom de la méthode et qu'il n'apporte rien. Je suis pour commenter mon code mais pour qu'il apporte qque chose.
Votre avis ? Vous mettez quoi comme commentaire pour vos javadoc ?
Merci pour vos avis !
Salut,
Pour les getter et les setters des classes la javadoc n'est pas tres utile. Personnellement moi je la mets (histoire d'avoir une doc complete). Par exemple je mets ceci pour un getter.
/** * Permet d'obtenir le nom de l'element. * @return le nom de l'element. * @see #setName(String name) */ public String getName(){
}
le tag @see est adapte ici et te renvoie au setter idem pour le getter. Et mem si ça te parait redondant comme commentaires, regarde un peu la javadoc du jsdk elle est garnie commentaires que tu qualifie de "redondants". Enfin pour finir je prefere faire les commentaires javadoc de toutes les classes, membres et methodes (meme privees) histoire d'avoir une documentation pour la personne qui eventuellement jetterait un coup d'oeil au code. Tout est question de gouts !!!!
Gabriel <cy_rainchapeau26@yahoo.fr> wrote in message news:<cg7n62$kd3$1@news-reader4.wanadoo.fr>...
Bonjour,
Je suis en train de développer un projet et je me pose une question :
Soit le prototype de méthode suivant :
/**
* getTableLangue renvoie le nom de la table Langue de l'id passé
en paramètre
* @param idLang
* @return le nom de la table Langue de l'id passé en paramètre
*/
public static String getTableLangue(byte idLangue){
...}
Je trouve que le commentaire est redondant par rapport au nom de la
méthode et qu'il n'apporte rien.
Je suis pour commenter mon code mais pour qu'il apporte qque chose.
Votre avis ?
Vous mettez quoi comme commentaire pour vos javadoc ?
Merci pour vos avis !
Salut,
Pour les getter et les setters des classes la javadoc n'est pas tres
utile. Personnellement moi je la mets (histoire d'avoir une doc
complete). Par exemple je mets ceci pour un getter.
/**
* Permet d'obtenir le nom de l'element.
* @return le nom de l'element.
* @see #setName(String name)
*/
public String getName(){
}
le tag @see est adapte ici et te renvoie au setter idem pour le
getter. Et mem si ça te parait redondant comme commentaires, regarde
un peu la javadoc du jsdk elle est garnie commentaires que tu qualifie
de "redondants".
Enfin pour finir je prefere faire les commentaires javadoc de toutes
les classes, membres et methodes (meme privees) histoire d'avoir une
documentation pour la personne qui eventuellement jetterait un coup
d'oeil au code. Tout est question de gouts !!!!
Je suis en train de développer un projet et je me pose une question :
Soit le prototype de méthode suivant :
/** * getTableLangue renvoie le nom de la table Langue de l'id passé en paramètre * @param idLang * @return le nom de la table Langue de l'id passé en paramètre */ public static String getTableLangue(byte idLangue){ ...}
Je trouve que le commentaire est redondant par rapport au nom de la méthode et qu'il n'apporte rien. Je suis pour commenter mon code mais pour qu'il apporte qque chose.
Votre avis ? Vous mettez quoi comme commentaire pour vos javadoc ?
Merci pour vos avis !
Salut,
Pour les getter et les setters des classes la javadoc n'est pas tres utile. Personnellement moi je la mets (histoire d'avoir une doc complete). Par exemple je mets ceci pour un getter.
/** * Permet d'obtenir le nom de l'element. * @return le nom de l'element. * @see #setName(String name) */ public String getName(){
}
le tag @see est adapte ici et te renvoie au setter idem pour le getter. Et mem si ça te parait redondant comme commentaires, regarde un peu la javadoc du jsdk elle est garnie commentaires que tu qualifie de "redondants". Enfin pour finir je prefere faire les commentaires javadoc de toutes les classes, membres et methodes (meme privees) histoire d'avoir une documentation pour la personne qui eventuellement jetterait un coup d'oeil au code. Tout est question de gouts !!!!
Gabriel
Salut,
Pour les getter et les setters des classes la javadoc n'est pas tres utile. Personnellement moi je la mets (histoire d'avoir une doc complete). Par exemple je mets ceci pour un getter.
/** * Permet d'obtenir le nom de l'element. * @return le nom de l'element. * @see #setName(String name) */ public String getName(){
}
le tag @see est adapte ici et te renvoie au setter idem pour le getter. Et mem si ça te parait redondant comme commentaires, regarde un peu la javadoc du jsdk elle est garnie commentaires que tu qualifie de "redondants". Enfin pour finir je prefere faire les commentaires javadoc de toutes les classes, membres et methodes (meme privees) histoire d'avoir une documentation pour la personne qui eventuellement jetterait un coup d'oeil au code. Tout est question de gouts !!!!
Merci, apparemment la question ne passione pas les foules :)
@+
Salut,
Pour les getter et les setters des classes la javadoc n'est pas tres
utile. Personnellement moi je la mets (histoire d'avoir une doc
complete). Par exemple je mets ceci pour un getter.
/**
* Permet d'obtenir le nom de l'element.
* @return le nom de l'element.
* @see #setName(String name)
*/
public String getName(){
}
le tag @see est adapte ici et te renvoie au setter idem pour le
getter. Et mem si ça te parait redondant comme commentaires, regarde
un peu la javadoc du jsdk elle est garnie commentaires que tu qualifie
de "redondants".
Enfin pour finir je prefere faire les commentaires javadoc de toutes
les classes, membres et methodes (meme privees) histoire d'avoir une
documentation pour la personne qui eventuellement jetterait un coup
d'oeil au code. Tout est question de gouts !!!!
Merci,
apparemment la question ne passione pas les foules :)
Pour les getter et les setters des classes la javadoc n'est pas tres utile. Personnellement moi je la mets (histoire d'avoir une doc complete). Par exemple je mets ceci pour un getter.
/** * Permet d'obtenir le nom de l'element. * @return le nom de l'element. * @see #setName(String name) */ public String getName(){
}
le tag @see est adapte ici et te renvoie au setter idem pour le getter. Et mem si ça te parait redondant comme commentaires, regarde un peu la javadoc du jsdk elle est garnie commentaires que tu qualifie de "redondants". Enfin pour finir je prefere faire les commentaires javadoc de toutes les classes, membres et methodes (meme privees) histoire d'avoir une documentation pour la personne qui eventuellement jetterait un coup d'oeil au code. Tout est question de gouts !!!!
Merci, apparemment la question ne passione pas les foules :)
@+
Black Myst
Gabriel wrote:
Bonjour,
Je suis en train de développer un projet et je me pose une question :
Soit le prototype de méthode suivant :
/** * getTableLangue renvoie le nom de la table Langue de l'id passé en paramètre * @param idLang * @return le nom de la table Langue de l'id passé en paramètre */ public static String getTableLangue(byte idLangue){ ...}
Je trouve que le commentaire est redondant par rapport au nom de la méthode et qu'il n'apporte rien. normale, il l'est
Je suis pour commenter mon code mais pour qu'il apporte qque chose.
Votre avis ? Effectivement, ce commentaire n'est pas tres utile, pour preuve, je ne
sais pas ce que fait ta méthode ! (c'est vrai que normalement, j'aurais quand meme un contexte...)
Vous mettez quoi comme commentaire pour vos javadoc ? /**
* Renvoie e nom de la table Langue de l'id passé en paramètre. * (peut-etre ajouter une courte description de ce qu'est une table * de langue) * @param idLang l'identifiant de la langue au format ISO-XXX (code * langues sur 2 caractères, fr=france, en=Anglais, de=allemand, ...) * @return le nom de la table Langue de l'id passé en paramètre, ou null * si la table n'existe pas. */
Je precise le type de valeur attendu pour l'id de la langue Je précise également que cette methode retourne null en cas d'erreur, d'une manière générale, je précise toujours quand une méthode accepte des parametres null et/ou renvois des resultat null... c'est tres important pour savoir s'il faut tester la valeur ou si on peut faire confiance...
Merci pour vos avis !
Un autre truc tres important, c'est le commentaire de la classe... c'est le plus important, et celui qu'on trouve le moins souvent.
Lorsqu'on créer une nouvelle classe, on doit etre en mesure d'expliquer dans ce commetaire : - a quoi sert la classe - pourquoi on l'a fait - comment l'utiliser si on ne sait pas expliquer ca avant de commencer à coder la classe, il est certainement nécessaire de repenser son diagramme globale .
Voila. a toi de commenter maintenant (la tache la plus ingrate et la plus importante !)
Gabriel wrote:
Bonjour,
Je suis en train de développer un projet et je me pose une question :
Soit le prototype de méthode suivant :
/**
* getTableLangue renvoie le nom de la table Langue de l'id passé en
paramètre
* @param idLang
* @return le nom de la table Langue de l'id passé en paramètre
*/
public static String getTableLangue(byte idLangue){
...}
Je trouve que le commentaire est redondant par rapport au nom de la
méthode et qu'il n'apporte rien.
normale, il l'est
Je suis pour commenter mon code mais pour qu'il apporte qque chose.
Votre avis ?
Effectivement, ce commentaire n'est pas tres utile, pour preuve, je ne
sais pas ce que fait ta méthode ! (c'est vrai que normalement, j'aurais
quand meme un contexte...)
Vous mettez quoi comme commentaire pour vos javadoc ?
/**
* Renvoie e nom de la table Langue de l'id passé en paramètre.
* (peut-etre ajouter une courte description de ce qu'est une table
* de langue)
* @param idLang l'identifiant de la langue au format ISO-XXX (code
* langues sur 2 caractères, fr=france, en=Anglais, de=allemand, ...)
* @return le nom de la table Langue de l'id passé en paramètre, ou null
* si la table n'existe pas.
*/
Je precise le type de valeur attendu pour l'id de la langue
Je précise également que cette methode retourne null en cas d'erreur,
d'une manière générale, je précise toujours quand une méthode accepte
des parametres null et/ou renvois des resultat null... c'est tres
important pour savoir s'il faut tester la valeur ou si on peut faire
confiance...
Merci pour vos avis !
Un autre truc tres important, c'est le commentaire de la classe... c'est
le plus important, et celui qu'on trouve le moins souvent.
Lorsqu'on créer une nouvelle classe, on doit etre en mesure d'expliquer
dans ce commetaire :
- a quoi sert la classe
- pourquoi on l'a fait
- comment l'utiliser
si on ne sait pas expliquer ca avant de commencer à coder la classe, il
est certainement nécessaire de repenser son diagramme globale .
Voila. a toi de commenter maintenant (la tache la plus ingrate et la
plus importante !)
Je suis en train de développer un projet et je me pose une question :
Soit le prototype de méthode suivant :
/** * getTableLangue renvoie le nom de la table Langue de l'id passé en paramètre * @param idLang * @return le nom de la table Langue de l'id passé en paramètre */ public static String getTableLangue(byte idLangue){ ...}
Je trouve que le commentaire est redondant par rapport au nom de la méthode et qu'il n'apporte rien. normale, il l'est
Je suis pour commenter mon code mais pour qu'il apporte qque chose.
Votre avis ? Effectivement, ce commentaire n'est pas tres utile, pour preuve, je ne
sais pas ce que fait ta méthode ! (c'est vrai que normalement, j'aurais quand meme un contexte...)
Vous mettez quoi comme commentaire pour vos javadoc ? /**
* Renvoie e nom de la table Langue de l'id passé en paramètre. * (peut-etre ajouter une courte description de ce qu'est une table * de langue) * @param idLang l'identifiant de la langue au format ISO-XXX (code * langues sur 2 caractères, fr=france, en=Anglais, de=allemand, ...) * @return le nom de la table Langue de l'id passé en paramètre, ou null * si la table n'existe pas. */
Je precise le type de valeur attendu pour l'id de la langue Je précise également que cette methode retourne null en cas d'erreur, d'une manière générale, je précise toujours quand une méthode accepte des parametres null et/ou renvois des resultat null... c'est tres important pour savoir s'il faut tester la valeur ou si on peut faire confiance...
Merci pour vos avis !
Un autre truc tres important, c'est le commentaire de la classe... c'est le plus important, et celui qu'on trouve le moins souvent.
Lorsqu'on créer une nouvelle classe, on doit etre en mesure d'expliquer dans ce commetaire : - a quoi sert la classe - pourquoi on l'a fait - comment l'utiliser si on ne sait pas expliquer ca avant de commencer à coder la classe, il est certainement nécessaire de repenser son diagramme globale .
Voila. a toi de commenter maintenant (la tache la plus ingrate et la plus importante !)
