Discussion :

[bedomon]

Bonjour tout le monde,

Voila je viens poser une petite question, concernant les conventions de nommage sur les commentaires de méthodes.

Faut-il un point pur terminer la première ligne du bloc de commentaire :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
    /**
     * .
     * Fait un appel au gestionnaire
     */

ou

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
    /**.
     * Fait un appel au gestionnaire
     */

J'ai parcourus la doc et je n'ai rien vu qui confortait cette façon de faire.

Pour information, c'est après avoir installé checkstyle dans netbeans que j'ai eu cette "erreur".

Merci d'avance

[thelvin]

Ce n'est pas une histoire de première ligne, mais de première phrase. Le premier point indique la fin de la première phrase.

C'est important parce que par convention, la première phrase est censée être une description rapide, droit au but, de la chose documentée.
Si plus d'explications sont nécessaires ou utiles, elles doivent être placées après le premier point.

Concrètement l'outil javadoc fourni avec le JDK, et les outils similaires, s'en servent pour générer la documentation des méthodes, constructeurs, champs et sous-classes.
D'abord il y a une liste rapide de tout ça, et des liens cliquables vers une documentation plus complète. La liste rapide ne contient que la première phrase du bloc, pour éviter d'être trop verbeux et surcharger la liste.
Le reste se situe dans la documentation plus fine, qu'on trouve en cliquant dans la liste rapide.

Conclusion : Mettre un point dès le début du commentaire n'a pas de sens. Ça fait juste "tais-toi checkstyle, je ne veux pas savoir ce que tu essaies de me dire."

[bedomon]

Donc si je reprend mon petit exemple je devrais le faire comme ci-dessous :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
/**
     *  Fait un appel au gestionnaire.
     * Le gestionnaire permet de gérer ce qui est gérable.
     */

Conclusion : Mettre un point dès le début du commentaire n'a pas de sens. Ça fait juste "tais-toi checkstyle, je ne veux pas savoir ce que tu essaies de me dire."

J'avoue que c'était un peu ce que je faisais, et si je suppose bien l'explication que tu viens de me donner repond à cette extrait de la doc oracle :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

Write the first sentence as a short summary of the method, as Javadoc automatically places it in the method summary table (and index).

Edit : C'est pour ca que dans netbeans, il met en gras ce qui se trouve avant le point (quand il y a du quelque chose avant)