Discussion :

[LinuxUser]

Bonjour,

Je voulais connaitre un peu pour vous les bonnes pratiques et conventions lorqu'on commente son code C++, ce qui pour vous est absolument à faire et à éviter.

J'aimerai aussi avoir votre avis sur deux choses:

1/ Doit-on absolument séparer prototype (headers) et implémentation (.cpp), ou peut implémenter par exemple les constructeurs et getters/setters dans le .h pour "alléger" le .cpp?
2/ Comment bien commenter un getter ou setter sans mettre un commentaire inutile du genre:

Code :

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

1
2
// return the string length
int getLength();

Merci de votre aide.

[Neckara]

Bonjour,

Pour commenter j'utilise des commentaire doxygen :

Code :

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

1
2
3
/** @brief Description
   @param int x : parametre
   @return bool : valeur de retour */

Avec @enum pour les énumérations, @mainpage pour la description du programme, etc...

Après, on ne devrait pas à avoir à mettre des commentaires dans le code (sauf cas exceptionnel) car ceci signifierais que le code n'est pas assez explicite.

Si tu veux "alléger" le .cpp c'est peut être que ta classe a trop de responsabilité, et il vaut mieux dans ce cas la faire plusieurs classes.

On ne met l'implémentation dans les .h uniquement quand on veut inliner des méthodes ou fonctions ou quand on utilise des templates.

[LinuxUser]

Intéressant, tu dis que le code en soit necessite peu voire pas de commentaire, j'ai toujours cru au contraire qu'il fallait "tout" commenter.

Mis à part les inline et template, pas de code (constructeurs par exemple) dans les .h si je comprends bien.

Par contre, pour en revenir aux commentaires, doit-on commenter une fonctions deux fois (une fois son prototype dans le .h et une seconde fois dans .cpp) ou juste dans le .h suffit?

.h

Code :

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

1
2
3
4
5
6
 
/**
* @desc calcul force correction with rolling mill's coefficients
* @return double - force corrected
*/
double forceCorrection();

.cpp

Code :

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

1
2
3
4
5
6
 
// on répète le commentaire du .h ou pas?
double forceCorrection()
{
...
}

[Neckara]

Intéressant, tu dis que le code en soit necessite peu voire pas de commentaire, j'ai toujours cru au contraire qu'il fallait "tout" commenter.

Trop de commentaires tuent le commentaire :

Code :

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

1
2
3
4
5
6
void foo(void)//fonction foo
{
       int i; //déclaration d'un entier nommé i
       if(true) //si vrai
             i = 7; // i vaut alors 7
}

Normalement sauf cas exceptionnels, un code bien indenté avec des noms de variables et de fonction explicites devraient suffire à faire comprendre ce que fait le code sans que des commentaires dans le code soit vraiment utiles (sauf commentaires style TODO etc...).
Par contre les commentaires doxygen permettent de générer une documentation qui permet à l'utilisateur de ne pas à avoir à fouiller dans le code pour pouvoir l'utiliser.

Par contre, pour en revenir aux commentaires, doit-on commenter une fonctions deux fois (une fois son prototype dans le .h et une seconde fois dans .cpp) ou juste dans le .h suffit?

Une seule fois suffit mais certaines personnes préfèrent les mettre dans le .cpp pour rendre la compilation plus rapide.

[kinaesthesia]

Pour ma part on ne commente que le header car c'est bel et bien ce fichier qui définit une classe.

Un autre programmeur va utiliser ta classe, il va simplement regarder le header pour connaître l'objet et non l'implémentation qu'il y a derrière. C'est de l'encapsulation.

Quand tu utilises une librairies, tu ne regardes pas le code source (sauf cas exceptionnel) ?

Les commentaires dans l'implémentation doivent être exceptionnel du genre :

// TODO
// FIXME
// Could be better

...

Mais uniquement pour toi /ou un autre dev qui devrait changer ton implémentation.


Pour les getters, je ne met point de code sauf s'il y a un quelconque traitement dedans.

[LinuxUser]

Pour ma part on ne commente que le header car c'est bel et bien ce fichier qui définit une classe.

Je suis d'accord, je pense la même chose.

Pour les getters, je ne met point de code sauf s'il y a un quelconque traitement dedans.

Par contre, pour moi, un getter() doit uniquement renvoyer une valeur sans aucun traitement (conversion, mise à l"chelle, ou autre), sinon ce n'est plus un getter() mais une fonction en soit et son appelation de getter devient trompeuse.

En gros, un getter devrait (ou doit si on est stricte) ressembler à cela:

Code :

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

1
2
3
4
5
// je sais pas si un commentaire est neccesaire ici, d'après kinaesthesia, non
double getValue()
{
  return m_value;
}

[Neckara]

Pour ma part on ne commente que le header car c'est bel et bien ce fichier qui définit une classe.

Un autre programmeur va utiliser ta classe, il va simplement regarder le header pour connaître l'objet et non l'implémentation qu'il y a derrière. C'est de l'encapsulation.

Personnellement, je pense que le programmeur ne devrait même pas regarder le header, la documentation (si possible doxygen) devant normalement lui suffire.

Même si je n'en suis pas très fan, le fait de mettre les commentaires dans le .cpp peut parfois être un gain de temps non-négligeable dans de très gros projets, en effet dès qu'on va modifier un commentaire dans un header, on va devoir recompiller tous les .cpp incluant ce header.

Pour les getters, je ne met point de code sauf s'il y a un quelconque traitement dedans.

Personnellement je les commente toujours, si possible j'essaye d'ajouter des précisions/informations sur la variable retournée.

Par contre une chose à ne jamais faire :
Ne mettre presque aucun commentaire sauf quelques jeux de mots avec getter et setter. ça ne fait pas tellement rire quand on reprend le code par la suite.

Par contre, pour moi, un getter() doit uniquement renvoyer une valeur sans aucun traitement (conversion, mise à l"chelle, ou autre), sinon ce n'est plus un getter() mais une fonction en soit et son appelation de getter devient trompeuse.

Je ne suis pas du tout d'accord, en quoi l'appellation serait-elle trompeuse?
L'utilisateur n'est pas censé savoir que la variable existe tel quel ou non.

[kinaesthesia]

Personnellement, je pense que le programmeur ne devrait même pas regarder le header, la documentation (si possible doxygen) devant normalement lui suffire.

Même si je n'en suis pas très fan, le fait de mettre les commentaires dans le .cpp peut parfois être un gain de temps non-négligeable dans de très gros projets, en effet dès qu'on va modifier un commentaire dans un header, on va devoir re-compiler tous les .cpp incluant ce header.

Pourquoi tu voudrais modifier un commentaire ? Car la fonction a changé ? tu peux très bien gérer ça du coté de ton makefile. Puis on ne change pas le commentaire d'une fonction subitement comme ça.

[LinuxUser]

Je ne suis pas du tout d'accord, en quoi l'appellation serait-elle trompeuse?
L'utilisateur n'est pas censé savoir que la variable existe tel quel ou non.

C'est seulement mon avis, un getter ne devrait que retourner une simple valeur sans traitement ni modification car pour moi c'est une opération ultra basique (voire atomique).
Si on a un besoin de traitement sur un membre, on fait une fonction pour cela, même si c'est un tout petit traitement.

Et parfois, appeller une fonction getSomething() alors qu'elle fait plus que juste renvoyer la valeur peut être trompeur, j'en ai fait récemment l'expérience, exemple:

Code :

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

1
2
3
4
5
6
7
class Foo
{
private:
  double m_force;
public:
  double getForce();
};

Pour moi getForce() doit ressembler à cela:

Code :

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

1
2
3
4
double getForce()
{
  return m_force;
}

Or la force retournée était bien celle que j'attendais, sauf lorsque j'affichais sa valuer lors de calcul intermédiaire, pour la simple et bonne raison qu'elle était converti (en Newton) à l'initialisation et lors du getter():

Code :

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

1
2
3
4
5
6
7
8
Foo::Foo(double force)
{
  m_force = force*9.81; 
}
double getForce()
{
  return m_force/9.81;
}

Donc si dans une focntion de Foo j'affiche la valeur de m_force elle sera "fausse" car je m'attends à avoir une valeur en Kg et non en Newton, surtout si aucun commentaire ne prévient.

Alors tu me diras qu'il suffit de modifier en:

Code :

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

1
2
3
4
5
6
7
class Foo
{
private:
  double m_forceNewton;
public:
  double getForceKg();
};

Et que tout ètait de la faute du développeur qui n'a rien commenter (et je suis d'accord), mais je suis pas trop fan de ce genre de choses.