[organisation] commentaire et documentation doxygen

**koala01** · 17/04/2010, 02h01

Salut,

Je m'interroge sur le moyen le plus efficace de faire cohabiter les commentaires et informations de licence avec la documentation doxygen.

En effet, l'idéal est d'avoir, dans chaque fichier, un cartouche rappelant la licence utilisée proche de

Code C++ :

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
/* This file is part of farfelue.
 *
 * farfelue is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * farfelue is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser Public License for more details.
 
 * You should have received a copy of the GNU Lesser Public License
 * along with Foobar.  If not, see <http://www.gnu.org/licenses/>.
 *
 * copyrigth (c) 2010 Philippe Dunski
 */

D'un autre côté, comme l'idéal est, malgré tout de fournir une documentation aussi complète que possible, il faudrait avoir les commentaires doxygen sous une forme proche de

Code C++ :

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

1
2
3
4
5
6
7
/** @file fichier.hpp include fichier.hpp
  * @brief what does this file
  * @ author philippe dunski
  * @ date 2010/04/07
  *
  * some more descriptive text
  */

En outre, je souhaiterais généraliser YAGNI, et, par conséquent, faire en sorte que la documentation doxygen gère la "todo list" pour chaque fichier, ce qui implique l'ajout, dans le cartouche propre au fichier, d'une ligne proche de

Code :

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

/** @todo add something */

par élément à rajouter en temps utile.

Et nous ne parlons même pas de la nécessité du cartouche des fonctions et des membres des différentes structures, ni de la nécessité de gérer la documentation de manière bilingue

Pour vous aider à imaginer à quoi risque de ressembler un fichier qui contiendrait toutes ces parties, cela ressemblerait en gros à

Code C++ :

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
/* This file is part of farfelue.
 *
 * farfelue is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * farfelue is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser Public License for more details.
 
 * You should have received a copy of the GNU Lesser Public License
 * along with Foobar.  If not, see <http://www.gnu.org/licenses/>.
 *
 * copyrigth (c) 2010 Philippe Dunski
 */
 
/** @file fichier.hpp include/fichier.hpp
  * @brief @english what does this file
  * @brief @french ce que fait ce fichier
  * @ author philippe dunski
  * @ date 2010/04/07
  *
  * @english some more descriptive text
  * @french une description plus détaillée
  * @todo @english add #1
  * @todo @french ajout #1
  * @todo @english add #2
  * @todo @french add #2
  */
 
#ifndef FICHIER_HPP
#define FICHIER_HPP
/** @brief @english class brief description
  * @brief @french description breve de la classe
  *
  * @english some more descriptive text (on multiple lines)
  * @french du texte plus précis (sur plusieurs lignes)
  */
class MaClass
{
    public:
        /*...*/
        /** @brief @english function that does something
          * @brief @french  fonction qui fait quelque chose
          * @param[in] parameter #1
          * @param[out] parameter #2
          * @return return value
          * @throw exception trhown in case of...
          */
       void foo()
 
};
 
#endif // FICHIER_HPP

Je suis personnellement généralement toujours partisan des commentaires, mais il faut avouer qu'ici, le taux de commentaire par ligne de code effective devient... vraiment important

Je me demande donc si nous n'aurions pas intérêt à séparer les commentaires doxygen, pourquoi pas en deux fichiers distincts, l'un permettant de générer la documentation en anglais sous la forme de:
fichier_en.dox

Code :

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
/** @english
  * @file fichier.hpp include/fichier.hpp
  * @briefwhat does this file
  * @ author philippe dunski
  * @ date 2010/04/07
  *
  * @english some more descriptive text
  * @todo @english add #1
  * @todo @english add #2
  *
  * @class MaClass
  * @brief class brief description
  * 
  * more descriptive class description
  *
  * @fn void MaClass::foo()
  * @brief function that does something
  * @param[in] parameter #1
  * @param[out] parameter #2
  * @return return value
  * @throw exception trhown in case of...
  */

et en fichier_fr.dox qui contiendrait... l'équivalent en français.

L'avantage de la technique, c'est qu'elle permet de garder des fichiers "épurés" (dans lesquels il n'y a pas pour ainsi dire plus de commentaires que de code), l'inconvénient majeur étant... la multiplication des fichiers à modifier:

On passerait de un ou deux fichiers à modifier à ... trois ou quatre fichiers à modifier à chaque fois... et on observerait une augmentation du nombre de fichiers dans les même proportions

De plus, je dois avouer que, selon moi, le cartouche expliquant les buts et la logique mise en oeuvre par une fonction a beaucoup plus sa place juste avant son implémentation que... juste avant sa déclaration (du moins, si les deux sont séparés), simplement parce que c'est typiquement le genre de chose dont le développeur qui travaille sur la fonction a besoin afin de s'assurer qu'il "respecte bien les règles".

L'utilisateur de la fonction, quant à lui est plutôt sensé... se référer à la documentation pour savoir si la fonction dont il envisage de se servir est adaptée à ses besoins

Comme vous le voyez, j'ai pu trouver du bon et du mauvais pour toutes les solutions, et, si l'idée de séparer clairement les commentaires de génération de documentation me plait énormément, je dois malgré tout avouer qu'elle n'est pas sans me provoquer un certain malaise.

Aussi, je préfères m'en remettre à votre jugement. Que préférez vous comme organisation

Séparer clairement les commentaires permettant la génération de documentation dans des fichiers prévus à cet effet
Placer l'ensemble des commentaires permettant la génération de documentation dans les fichiers d'en-tête
Placer "le stricte minimum" des commentaire de génération de documentation dans les fichier d'en-tête, et le reste dans les fichiers d'implémentation
placer une partie des commentaire de documentation dans les fichiers d'en-tête, une autre dans les fichiers d'implémentation, et le reste dans des fichiers prévus à cet effet

Merci d'avance pour vos avis.

**metagoto** · 17/04/2010, 05h20

Je "pense" que de minimiser le nombre de fichiers ne ferait pas de mal...

Pour les commentaire: il faudrait qu'ils soient au minimum en anglais.
Anglais en priorité, français, chinois ou thai en option.

Invité · 17/04/2010, 09h28

Quelques commentaires...

Comme metagoto, si on peut éviter les fichiers trop nombreux, c'est bien! Et les commentaires, en une seule langue, le problème d'avoir deux commentaires, c'est quand ils divergent : on a alors 3 sources d'info, les deux commentaires et le code. Donc un commentaire unique, svp...

Je crois que le principe d'avoir les commentaires, qui servent de doc, dans le code, repose sur l'idée qu'on a plus de chance, en voyant la "doc" quand on édite le code, de maintenir celle ci à jour. Les déplacer dans des fichiers externes, ca ne tuerait pas un peu le principe de Doxygen?

Maintenant, le but des commentaires, c'est qu'ils restent courts. Mon impression est qu'il faudra probablement adopter une approche mixte :

- dans le code, des commentaires "pour doxygen", qui sont courts, et se limitent à ce qui est vraiment nécessaire. Des choses comme

Code :

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Opens the file named file
void OpenFile(string file) {
}

ou

//loop on i
for(int i=0;i<n;i++) {
}

ou

/* Function Add, adds the result
    syntax r=Add(a,b);
    a first parameter
    b second parameter
    r result of the add function
*/
int Add(int a,int b) {
}

Je pense qu'on peut partir de l'idée que c'est notre ardente obligation de les tuer à vue (je proposerais bien un poste de "nettoyeur" dans l'équipe, qui aurait pour fonction de débarasser le code de tout ce qui est devenu inutile, on ne fait jamais ca, et pourtant...)

- hors du code, des "notes techniques", rangées dans un répertoire, qui précisent des points transversaux, ou trop longs pour être mis dans les commentaires. Idéalement, il faudrait que doxygen les "gère" (je ne connais pas Doxygen).

Pour la licence, je ne crois pas qu'il soit utile d'avoir un gros pavé dans chaque module. GNU fait cela pour évangéliser, je pense, nous on s'en moque. Donc un fichier "licence.txt" et une référence vers lui au début de chaque fichier?

Pour le copyright, j'ai l'impression qu'il y a deux façons de faire: soit on met nos noms, soit on met un nom collectif (The Farfelue Team, avec des majuscules parce que ca fait drolement sérieux) et on précise qui c'est dans un fichier. Je n'ai pas de préférence, mais décidons ca vite fait.

Francois

**Goten** · 17/04/2010, 12h04

Oui oui, en anglais les commentaires, (tout dans les fichiers quoi). Si ce n'est pour que ça soit international, au moins pour ne pas avoir de problème de locale. (oui je n'en peux plus d'ouvrir des fichiers de windowsien qui me pètent à la gueule :/)

gl · 17/04/2010, 16h11

Envoyé par koala01

De plus, je dois avouer que, selon moi, le cartouche expliquant les buts et la logique mise en oeuvre par une fonction a beaucoup plus sa place juste avant son implémentation que... juste avant sa déclaration (du moins, si les deux sont séparés), simplement parce que c'est typiquement le genre de chose dont le développeur qui travaille sur la fonction a besoin afin de s'assurer qu'il "respecte bien les règles".

En tant qu'utilisateur de bibliothèque, j'apprécie d'avoir les commentaires doxygen dans le header (et donc avant la déclaration). En effet certains éditeurs affichent le cartouche de commentaires d'une fonction lorsqu'on laisse le curseur sur le nom de ladite fonction, ce qui est très pratique et évite de basculer sur la documentation pour vérifier un simple petit détail.

En outre par expérience, il est plus simple de générer la doc utilisateur depuis les headers que depuis l'implémentation car ainsi, tout ce qui est privé à l'implémentation n'apparait tout simplement pas sans avoir rien de particulier à faire.

**koala01** · 17/04/2010, 16h11

Effectivement, on peut éviter le rappel de la licence dans tous les fichiers, et se contenter d'un fichier séparé qui la reprend

De même, on peut se "contenter" d'une documentation et de commentaires en anglais, du moins dans un premier temps (il faut cependant prendre en compte que le besoin de traduction risque de se faire sentir par la suite

)

Et je suis également d'accord sur le fait qu'il est préférable de limiter autant que possible le nombre de fichiers.

Par contre, pour que la documentation doxygen soit complète, nous n'échapperons pas à un certain nombre de fichiers externes: il en faudra au minimum un qui liste les différents espaces de noms (mais on peut envisager de tous les regrouper dans "namespace.dox"

)

En outre, je préférerais quand même avoir un cartouche en ce qui concerne les différents fichiers (au minimum les fichier d'en-tête), ne serait-ce que pour clairement indiquer qui a créé le fichier, le but du fichier, et "ce qui reste à faire".

Pour ce cartouche, je proposerais le format doxygen:

Code C++ :

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

1
2
3
4
5
6
7
8
/** @file fichier.hpp
  * @brief some short description
 
  * @author nom de l'auteur
  * @date date de création
  * @todo todo#1
  * @todo todo#2
  */

De cette manière, on peut "institutionnaliser" YAGNI, et on en arrive, par exemple, à un fichier définissant les politiques de positionnement prendrait une forme proche de

Code c++ :

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
/** @file tposition.hpp include/tposition.hpp
  * @brief provide polities for positionning
  * @author Philippe Dunski koala01<at>free<dot>fr
  * @date 2010/04/17
  * @todo provide a 3D position flag
  * @todo provide 3D positionning policy
  * @todo provide a "make3DPosition" function
  * @todo provide common typedef's
  *
  */
/** @brief a flag for 2D positionning policy
  *
  */
struct position2D_flag{};
/** @brief unspecialized Position structure declaration
  *
  */
template <tyepname T, class Flag> struct Position;
/** @brief partially 2D specialized position structure
  *
  */
template <typename T>
class Position<T, position2D_flag>
{
    typedef T value_type;
    value_type x;
    value_type y;
};
/** @brief create a 2D position structure
  *
  * @param[in] x : value that represent position on X axis value
  * @param[in] y : value that represent position on Y axis value
  * @return position<T, position2D_flag> created position representation
  *
  */
template <typename T>
Position< T, position2D_flag> make2DPosition(T x, T y)
{
    Position<T, position2D_flag> p;
    p.x=x;
    p.y=y;
    return p;
}

(code écrit "à la va vite"

)

Cela vous conviendrait-il

**koala01** · 17/04/2010, 16h48

Envoyé par gl

En tant qu'utilisateur de bibliothèque, j'apprécie d'avoir les commentaires doxygen dans le header (et donc avant la déclaration). En effet certains éditeurs affichent le cartouche de commentaires d'une fonction lorsqu'on laisse le curseur sur le nom de ladite fonction, ce qui est très pratique et évite de basculer sur la documentation pour vérifier un simple petit détail.

En outre par expérience, il est plus simple de générer la doc utilisateur depuis les headers que depuis l'implémentation car ainsi, tout ce qui est privé à l'implémentation n'apparait tout simplement pas sans avoir rien de particulier à faire.

Cela ne me dérange absolument pas d'avoir le cartouche des fonctions dans le fichier d'en-tête, ne serait-ce que parce que du point de l'utilisateur, c'est effectivement plus facile du moment qu'il apparaisse quelque part

La politique générale serait donc de "tirer à vue" sur les codes

qui ne proposent pas le cartouche fichier
qui ne proposent pas le cartouche pour les fonction publiques dans le fichier d'en-tête
qui désactivent du code d'une manière ou d'une autre (hormis bien sur les compilation conditionnelles nécessaires à la compatibilité )
qui présentent des commentaires inutiles

Est-ce que cela vous parrait cohérent

gl · 17/04/2010, 16h59

Envoyé par koala01

Est-ce que cela vous parrait cohérent

Oui.

Par contre concernant le point

Envoyé par koala01

qui présentent des commentaires inutiles

attends toi à avoir de longue discussion quant à savoir ce qui est utile/inutile comme commentaire.

**koala01** · 17/04/2010, 17h06

Envoyé par gl

attends toi à avoir de longue discussion quant à savoir ce qui est utile/inutile comme commentaire.

Sans blague

Ne t'en fais pas, je m'y attend effectivement tout à fait...

A tel point que j'envisage de clairement dire quel type de commentaire est utile, de manière à ne laisser aucun doute planer sur ce point

**Luc Hermitte** · 18/04/2010, 12h27

Accessoirement, de la doc doxygen sans utilisation de groupes ou de page d'intro (comme fait sur ASL), je trouve ça complètement inexploitable.

**koala01** · 18/04/2010, 15h00

Il est vrai que le fait d'avoir une documentation spécifique pour les développeurs et une autre spécifique pour les utilisateurs peut faciliter les choses...

Mais, suffit-il de rajouter un "@group" au cartouche d'une fonction ou d'une classe

Si tel est le cas, nous pouvons effectivement l'intégrer dans les règles à suivre

[organisation] commentaire et documentation doxygen

Farfelue

Discussions similaires

Partager

Partager