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).