Discussion :

[fardon57]

Bonjour,

Je m'interroge au sujet de la javaDoc, a votre avis, doit on tout documenter, meme les variables et methodes private d'une classe ?

Je suppose que cela ne presenterais que peux d'interet pour une doc dont le but est de servir d'aide aux utilisateurs de l'API, mais cela pourrait etre interressant sur un projet en plein developpement, non ?

Merci !

[Torg666]

Bonjour,

Je m'interroge au sujet de la javaDoc, a votre avis, doit on tout documenter, meme les variables et methodes private d'une classe ?

Je suppose que cela ne presenterais que peux d'interet pour une doc dont le but est de servir d'aide aux utilisateurs de l'API, mais cela pourrait etre interressant sur un projet en plein developpement, non ?

Merci !

Heu la javadoc c'est surtout destiné à des developpeurs, donc pour un utilisateur non developpeur, à moins de vouloir le faire , ca ne present pas d'interet. Lui aura plutot besoin d'une doc utilisateur.

[fardon57]

Heu la javadoc c'est surtout destiné à des developpeurs, donc pour un utilisateur non developpeur, à moins de vouloir le faire , ca ne present pas d'interet. Lui aura plutot besoin d'une doc utilisateur.

On est bien d'accord ! Mais lorsque je parle d'utilisateur, je pense a des developpeurs utilisants nos classe dans leur projet et cherchant a comprendre comment cela fonctionne. Ils sont donc utilisateurs de notre classe.
Ont-ils besoin de doc sur des methodes private ?

Et pour un developpement en equipe, doit-on documenter ses methodes privates ? Cela pourrait s'averer utile pour la comprehension du code.

[michel.di]

Il y a aussi une autre manière de voir le code.
Tes noms de méthodes, attributs peuvent être très explicites ce qui permet de se "passer" de la Javadoc!
Il faut toujours la Javadoc pour expliquer les paramètres à passer et ceux de retour mais tu n'as pas à expliquer ce que ta méthode fait!

[entreprise38]

Houyaaaaa, et bonjour la tête du code

Plus sérieusement, tu trouveras facilement des documents sur les "bonnes pratiques" concernant la Javadoc, y compris sur le site de Sun ( http://java.sun.com/j2se/javadoc/writingdoccomments/ ).

Pour commencer :
- ni trop de doc (ça tue la doc), ni pas assez (car "tout est marqué dans la doc", me disait un excellent prof).
- des commentaires qui veulent dire quelque chose : exit le commentaire du style "si résultat égal à 100" au dessus d'un "if (result == 100)" ^^. Les commentaires ne sont pas là pour faire apprendre Java aux autres, ils sont là pour dire à quoi sert ton code.
Cela peut aussi être utile pour déboguer ton code : en général, après 2 mois, tu es content de retrouver un commentaire qui explique le rôle de l'expression régulière un tantinet ardue, et que tu dois corriger/changer
- les commentaires sur les attributs et méthodes public/protected/default seront utiles à tous les développeurs : ceux qui utiliseront ton code, et ceux qui maintiendront ledit code. Ils seront présents dans la Javadoc générée (format HTML & co).
- les commentaires sur les attributs et méthodes private : cela peut être sacrément utile pour celui ou ceux qui maintiendront ton code. Biensûr, ils n'auront rien à faire dans la Javadoc générée.
Le reste, tu le trouveras facilement.