Documentation du code

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:

Citation:

---

Envoy� par 3DArchi

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 :aie:)

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

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� ?

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 :

Citation:

---

getValue()
Get value.

---

:aie:

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.

Citation:

---

Envoy� par 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 !)

---

Citation:

---

Envoy� par 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� ?

---

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:

Citation:

---

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

Citation:

---

Envoy� par LittleWhite

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 :

Citation:

---

\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:

---

1 2 3 4

typedef bool status; static const status SUCCESS = true; static const status FAILED = false;

---

Puis des commentaires de types :

Citation:

---

\return SUCCESS if function succeeds, otherwise FAILED

---

:aie:

Si je reprend

Citation:

---

\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 :

Citation:

---

/*! \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.

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 ?

Salut,

Citation:

---

Envoy� par LittleWhite

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.

Citation:

---

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.

Citation:

---

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:

---

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