Discussion :

[LittleWhite]

Bonjour à tous,

Aujourd'hui j'apporte une question non pas technique mais pratique.

Habituellement, je documente mon code avec Doxygen. J'ai cette habitude et je tiens à faire la documentation pour tout les projets que je réalise (même les persos, où il n'y a que moi pour lire le code)

Dans la théorie, Doxygen nous force à documenter toutes les fonctions que l'on va créer. Personnellement, j'aime bien avoir des getter dans mon code (c'est essentiel, même), et la documentation des getters est vraiment rébarbative.
De plus, si une classe Sprite à une méthode draw(), comment puis je documenter correctement cette fonction, sachant que son nom indique ce qu'elle fait ?

Je pose la question, car je viens de lire ceci:

Sur les commentaires et la documentation : toute ligne doit apporter une information qui n'est pas déjà fournie par ailleurs. Par expl, inutile de commenter ce qui est évident à la lecture du code. Ou ne pas produire de documentation qui soit l'exact reflet du code. Chacun doit avoir son niveau pertinent d'information.

Alors que dois je faire pour ma fonction draw()? Je vais la documenter du genre:
"Dessinne mon sprite".
(Logique, elle s'appelle draw() la fonction, elle ne va pas traire une vache )

Donc, ma question est: Que dois je faire dans ces cas là ?
Sachant que écrire la documentation prend du temps et si doit documenté plein de getter, je vais vite être ennuyé (et donc, bien souvent, ne plus être efficace / faire du copier-coller ). De plus, j'aimerai que ma documentation soit claire (évidemment).

Merci pour vos futurs conseils

[dragonjoker59]

Je dirais pour ta fonction draw, décrire ses spécificités, si elle en a : "dessine le sprite à l'envers puis fais une seconde passe en mettant à l'endroit ce qu'il faut" (par exemple, hein !)

[Heimdall]

Salut,

Et ne faudrait-il pas également spécifier ce que fait la fonction en cas d'erreur, et quels types d'erreur peut être rencontré ?

[ymoreau]

Je serais d'avis du post de 3DArchi que tu cites, s'il y a des précisions à apporter sur le comportement de la fonction tu documentes, si le nom de la fonction est suffisant pour comprendre son rôle alors autant ne pas documenter. Doxygen te listera de toute façon la fonction, il n'y aura juste pas de description.

Parce que bon, ce genre de doc c'est juste la perte de temps :

getValue()
Get value.

[nirgal76]

Si tes fonctions et variables sont bien nommées, c'est déjà une partie de la documentation de faite.
Et donc, pas besoin de les documenter plus, c'est une perte de temps et de la redondance d'info => perte de lisibilité.
Tu peux par contre documenter ses arguments, le type de retour et les erreurs.

[LittleWhite]

Je dirais pour ta fonction draw, décrire ses spécificités, si elle en a : "dessine le sprite à l'envers puis fais une seconde passe en mettant à l'endroit ce qu'il faut" (par exemple, hein !)

Salut,

Et ne faudrait-il pas également spécifier ce que fait la fonction en cas d'erreur, et quels types d'erreur peut être rencontré ?

D'ailleurs, ma fonction draw() va en fait, appeler une méthode spécifique à une bibliothèque. Sachant que j'ai fait en sorte de pouvoir changer la bibliothèque native de dessin très facilement, les erreurs retournées par cette fonction ne peuvent pas être décrit ici.
Le but de la fonciton est juste de dessiner un sprite, soit d'appeler la fonction de la bibliothèque native, avec la position du sprite actuel, et plop.
Donc, oui je documente les arguments que prend ma fonction draw ... mais dans la brève description de la fonction ... je me retrouve à dire:

Dessine le sprite

Exemple de ma documentation actuelle:
http://code.google.com/p/openawars/s...Game/Map.h#153
Et un getter:
http://code.google.com/p/openawars/s...Game/Map.h#175

Comme dit YoniBlond, mieux vaut peut être ne rien dire sur les getter ...

[3DArchi]

Alors que dois je faire pour ma fonction draw()?

preconditions et postcondition pour les fonctions, invariants pour les classes.
Ensuite, draw je me doute de ce que cela doit faire

Exemple pris (presque) au hasard dans ta doc :

\return true if all goes right

Diable ! Quelle originalité. Tu connais une fonction qui retourne true quand elle échoue ? Je taquine un peu, mais des fois on vois des redéfinitions de type :

Code :

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

1
2
3
4
 
typedef bool status;
static const status SUCCESS = true;
static const status FAILED = false;

Puis des commentaires de types :

\return SUCCESS if function succeeds, otherwise FAILED

Si je reprend

\return true if all goes right

Ca implique quoi si ça retourne false ? J'ai un moyen de me récupérer ? Je jette l'objet à la poubelle ? Ca fonctionne en mode dégradé ? Je peux récupérer un code d'erreur quelque part ? Ça jette une exception ? etc.

J'en prend une autre :

/*! \fn bool Map::drawTerrain(const NE::Renderer& r, const Camera& c, const unsigned int time)
* \brief Draw the terrain map
* \param r the NE::Renderer to use to draw the Map
* \param c The Camera (used to draw the correct part of the Map)
* \param time the actual time (for animation)
* \return true if all goes right
*/

Tout les mots de ton commentaire sont explicitement dans le code : Map::draw Terrain.

[LittleWhite]

Euh oui, certes ma documentation est très bidon.

Sachant que:

La fonctionne dessine (je n'ai jamais vu loupé une telle fonction venant de la SDL). Sauf que si une autre implémentation est fait, ce n'est pas la SDL qui dessine.
Selon l'autre implémentation ... des exceptions peuvent être lancé ... mais cela n'a jamais été prévu O_o
De plus, si elle échoue, bah on sait qu'elle a échoué, et donc que ce n'est pas dessiné ... mais rien de plus (true == dessin, false == pas dessin).

Comment dois je commenté tout cela ?

[3DArchi]

Salut,

De plus, si elle échoue, bah on sait qu'elle a échoué, et donc que ce n'est pas dessiné ... mais rien de plus (true == dessin, false == pas dessin).

Comment dois je commenté tout cela ?

C'est un peu ce que je voulais pointer. Les informations intéressantes n'y sont pas à priori. Normalement, avec des preconditions/postconditions on peut avoir une vision de ces limites. Que tu peux compléter de façon - formelle.

Sauf que si une autre implémentation est fait, ce n'est pas la SDL qui dessine.
Selon l'autre implémentation ... des exceptions peuvent être lancé ... mais cela n'a jamais été prévu O_o

Typiquement, dans un .h, je suis supposé complètement ignorer l'implémentation.

La fonctionne dessine (je n'ai jamais vu loupé une telle fonction venant de la SDL).

Pourquoi faire toujours retourner vrai à une fonction ? Ton code au niveau de l'appelant peut ressembler à

Code :

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

1
2
3
4
5
6
7
8
9
10
11
(void)fonction(); // (1)
// ou
if(fonction()) //(2)
{
   log_erreur();
}
// ou
if(!fonction() //(3)
{
   assert(false);
}

(1) : ton type retour ne sert visiblement à rien puisqu'il n'est jamais utilisé
(2) : tu exécute un code de vérification alors que jamais tu ne retournes false. Totalement inefficace en temps d'exécution et rend le code illisible. => utilises exceptions, ce sera + efficace.
(3) : les posts conditions se vérifient plutôt à la fin de la fonction plutôt que par l'appelant (qui a en charge les préconditions).