Discussion :

[flamme34]

Bonjour,

Mes collègues et moi même souhaitons définir des conventions de codage communes. C'est dans cette optique que je vous écrit aujourd'hui, car a priori les habitudes de codages ont du évoluer avec le temps.

personnellement on m'a appris les règles suivantes :

- un C majuscule devant les nom de Classe type CClass (reste de Visual studio)
- le préfixe p_ pour les paramètres
- une majuscule en début de nom de fonctions, et méthodes
- une minuscule en début de variables et attributs
- une entête avec les auteur, nom et rôle du fichier ainsi qu'un historique du fichier
- une entête avec nom et rôle de chaque fonction dans les points cpp

mais comme je l'ai dis a priori les habitudes de codage ont du changer car certains de mes collègues ne sont pas d'accord avec celle ci .

Donc dans le but de mieux coder, pourriez vous me donner vos conventions de codage, et les justification de celles-ci.

[Bousk]

Bonjour,

il existe à peu près autant de conventions de nommage que d'équipes donc libre à vous de définir ce que vous voulez (majuscules, minuscules, préfixes, suffixes, ...)

La seule chose dont je sois sûr c'est que

- une entête avec les auteur, nom et rôle du fichier ainsi qu'un historique du fichier

ça sert strictement à rien, sauf si vous êtes payés à la ligne ou au caractère/poids du fichier.
Sérieusement, n'importe quel serveur de versionning remplira cette tâche 10000..00 fois mieux que quiconque.
Sans compter que c'est ultra-chiant à maintenir, modifier à chaque fois etc...

- une entête avec nom et rôle de chaque fonction dans les points cpp

Les trucs à la javadoc ça a l'air sympa, mais en pratique, c'est encore du boulot superflu de maintenance.
On va pas relancer le débat sur la doc, mais "la meilleur doc, c'est le code", au moins t'es sûr qu'elle est à jour.
Donc bien nommer variables, méthodes etc.. plutôt qu'un pompeux paragraphe de commentaires pour expliquer que "la fonction Toto qui a pour 1° paramètre un entier qui représente son âge, et pour 2° paramètre un entier qui est sa taille, retourne le produit de l'age par la taille".

[white_tentacle]

Les trucs à la javadoc ça a l'air sympa, mais en pratique, c'est encore du boulot superflu de maintenance.
On va pas relancer le débat sur la doc, mais "la meilleur doc, c'est le code", au moins t'es sûr qu'elle est à jour.
Donc bien nommer variables, méthodes etc.. plutôt qu'un pompeux paragraphe de commentaires…

Le paragraphe de commentaires est là pour aller au-delà de ce que la signature peut exprimer. Par exemple :
- je renvoie un pointeur : il est toujours non nul
- je prends un entier en paramètre : il doit être dans l’intervalle X
- ma fonction est de complexité O(n)
- etc

Sinon, pour les normes de codage, de toute façon, en C++, avec l’intégration de plein de bibliothèques qui ont chacune leur norme, ça finit toujours par être moche.

Il y a juste ce truc :

- le préfixe p_ pour les paramètres

Que je trouve très moche (et sujet à confusion car certains l’utilisent parfois pour « pointer »).

[Ehonn]

Voici quelques raisons qui sont "contres" celles que tu proposes (pour montrer que l'inverse est valide aussi)

- un C majuscule devant les nom de Classe type CClass (reste de Visual studio)

On peut aussi faire comme la bibliothèque standard et Boost: std::vector, std::map, std::string.

- le préfixe p_ pour les paramètres

Pour les attributs de classe, j'utilise : m_ pour les attributs, s_ pour static, r_ pour les références, et donc : p_ pour les pointeurs.
Cela permet d'avoir le vrai nom disponible pour les accesseurs (quand cela a du sens).

- une majuscule en début de nom de fonctions, et méthodes

C'est assez rare ça, j'ai vu ça uniquement dans la SFML 1.6 et cela a été "corrigé" dans la SFML 2.

- une minuscule en début de variables et attributs

Le plus courant.

- une entête avec les auteur, nom et rôle du fichier ainsi qu'un historique du fichier

Comme dit avant, le gestionnaire de version fait ça pour toi (et mieux que toi).
Par contre, tu peux / dois mettre les auteurs avec copyright + résumé licence. Cela est même obligatoire si tu veux utiliser certaines licences (comme celles de GNU).

- une entête avec nom et rôle de chaque fonction dans les points cpp

J'utilise la Doxygen. Dans les .hpp car je n'ai pas de .cpp.
De toute façon, je préfère la mettre dans le .hpp car si on a pas accès à la Doxygen (ou pas dans la bonne version) on a forcément accès aux .hpp mais pas forcément aux .cpp.

[therwald]

J'utilise la Doxygen. Dans les .hpp car je n'ai pas de .cpp.
De toute façon, je préfère la mettre dans le .hpp car si on a pas accès à la Doxygen (ou pas dans la bonne version) on a forcément accès aux .hpp mais pas forcément aux .cpp.

Le seul intérêt de le mettre plutôt dans les .cpp c'est que ça évite de recompiler une tonne de code juste pour une correction dans un commentaire...
Ceci dit ce n'est pas possible pour certains éléments:
ex:

• si tu veux donner quelques infos sur une classe, qui ne se voit que dans le header
• si tu utilises des type paramétriques, vu qu'avec les templates la division .hpp/.cpp ne tient pas

[ternel]

Bonjour,

Mes collègues et moi même souhaitons définir des conventions de codage communes. C'est dans cette optique que je vous écrit aujourd'hui, car a priori les habitudes de codages ont du évoluer avec le temps.

personnellement on m'a appris les règles suivantes :

- un C majuscule devant les nom de Classe type CClass (reste de Visual studio)
- le préfixe p_ pour les paramètres
- une majuscule en début de nom de fonctions, et méthodes
- une minuscule en début de variables et attributs
- une entête avec les auteur, nom et rôle du fichier ainsi qu'un historique du fichier
- une entête avec nom et rôle de chaque fonction dans les points cpp

mais comme je l'ai dis a priori les habitudes de codage ont du changer car certains de mes collègues ne sont pas d'accord avec celle ci .

Donc dans le but de mieux coder, pourriez vous me donner vos conventions de codage, et les justification de celles-ci.

Les noms les plus lus sont les noms des fonctions, méthodes et types.
Je préconise personnellement de ne mettre aucune majuscule à ceux-ci, vu qu'on ne peut pas intervertir ces noms entre eux. *

Les autres noms relativement visibles sont les attributs.
S'ils sont publics, un nom simple est préférable, donc sans préfixe.
S'ils sont privés, m_ est usuel.

Les variables locales ne posent généralement pas de problèmes, et je les laisse comme des attributs publics.

Tout l'enjeu sera d'avoir des noms descriptifs.
Ne pas savoir que mettre comme nom de variable locale m'indique en général que la fonction est trop grosse, et que je dois pouvoir la diviser.
Rien que parce qu'il existe des noms comme temp et returned.

Par ailleurs, je déconseille fortement les nommages javaesques telles que getMachin() et setMachin().

PS: * concernant les noms à plusieurs mots, il y a deux conventions: nomComplexe et nom_complexe. Les deux sont fréquents.
Personnellement, je mets des _ pour les noms de type, et des majuscules aux noms de variables.

[TropMDR]

Tu peux t'inspirer de ca: http://google-styleguide.googlecode....k/cppguide.xml

[Neckara]

Tu peux t'inspirer de ca: http://google-styleguide.googlecode....k/cppguide.xml

Certaines choses sont en effet intéressantes mais d'autres...

Use the C++ keyword explicit for constructors with one argument.

=> Cela dépend si on veut avoir des conversions implicites ou non.

Typically a variable would be called foo_ and the accessor function foo(). You may also want a mutator function set_foo().

Mauvaise idée

All parameters passed by reference must be labeled const.

J'ai du mal à comprendre pourquoi

We do not allow default function parameters

De même, à première vu je ne vois pas l'intérêt

We do not use C++ exceptions.

Dommage de s'en passer quand c'est justifié

Use streams only for logging.

Do not use lambda expressions, or the related std::function or std::bind utilities.

OO

Dommage que toutes ces consignes ne soient pas justifiée par un petit texte.

[TropMDR]

(Pourquoi quand je repond avec citation, je perds le niveau precedant de citation??)

Use the C++ keyword explicit for constructors with one argument.

=> Cela dépend si on veut avoir des conversions implicites ou non.

L'idee est d'avoir un linteur qui te crie dessus si tu oublies "explicit", et une instruction explicite pour le linteur quand tu veux vraiment un constructeur implicite (ce qui est tres tres rare)

Typically a variable would be called foo_ and the accessor function foo(). You may also want a mutator function set_foo().

Mauvaise idée

Pourquoi ca? C'est au contraire tres agreable quand tu lis le code. blah => variable locale. blah_ => variable d'instance

All parameters passed by reference must be labeled const.

J'ai du mal à comprendre pourquoi

Si tu veux muter la variable, passe par pointeur.

We do not allow default function parameters

De même, à première vu je ne vois pas l'intérêt

Cette regle est nettement plus discutable, mais tu peux obtenir le meme resultat avec de l'overloading.

We do not use C++ exceptions.

Dommage de s'en passer quand c'est justifié

C'est plus pour des raisons historiques. Apres, les exceptions ont un paquet d'interaction complexes avec d'autres fonctionnalites du langage, et n'a pas de support a la Java pour annoter les fonctions. Donc avoir un retour explicite d'erreur rend le code plus simple a comprendre, et force l'appelant a traiter les erreurs potentielles.

Use streams only for logging.

Discutable aussi.

Do not use lambda expressions, or the related std::function or std::bind utilities.

OO

Ca, faut oublier

[Neckara]

L'idee est d'avoir un linteur qui te crie dessus si tu oublies "explicit", et une instruction explicite pour le linteur quand tu veux vraiment un constructeur implicite (ce qui est tres tres rare)

D'accord, je n'avais pas compris cela. C'est en effet assez intéressant.

Pourquoi ca? C'est au contraire tres agreable quand tu lis le code. blah => variable locale. blah_ => variable d'instance

Je parlais surtout d'avoir des accesseurs/mutateurs

Si tu veux muter la variable, passe par pointeur.

Pourquoi ne pourrait-on pas faire de même avec des références

Do not use lambda expressions, or the related std::function or std::bind utilities.

OO

Ca, faut oublier

Oublier la "règle" ou oublier les lambda, et consort ?

[Iradrille]

Pourquoi ne pourrait-on pas faire de même avec des références

Probablement qu'ils ont préférés imposer le passage par pointeur pour faciliter la relecture du code : pas besoin de se poser de questions ou de regarder le prototype de la fonction, si on ne passe pas de pointeur l'objet ne sera jamais modifié.

Puis maintenant, comme pour les exceptions, std::bind, etc... Ils ont une grosse codebase qui ne les utilisent pas, donc ils les interdisent pour garder un style cohérent.

[TropMDR]

Je parlais surtout d'avoir des accesseurs/mutateurs

On peut reformuler "dans le rare cas ou un accesseur/mutateur est justifie, la syntaxe est..."

Pourquoi ne pourrait-on pas faire de même avec des références

C++ est un langage enorme (d'aucun dirait monstreux). Le but d'une convention comme ca est de le limiter pour le rendre

1. Plus accessible
2. Moins surprenant
3. Coherent

Oui, tu peux muter via une reference! Les references ont meme un gros avantage sur les pointeur: pas de risque de nullref (bon, toujours un risque que l'objet reference ait disparu...), mais ont le desavantage (en cas de mutation) d'etre tres discrete. Par exemple, si tu regardes ce code:

Code :

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

1
2
string some_string("blah blah blah");
string another_string = DoSomething(some_string);

quelle est la valeure de some_string a la fin? Aucune idee, ca depend de la signature de DoSomething. Si la fonction prend un parametre par reference mutable, some_string peut changer. Maintenant si la base de code respecte la convention que les passages par reference sont forcement const, en regardant ce simple morceau de code, tu sais que some_string n'a pas changee. Et quand ca peut changer

Code :

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

1
2
string some_string("blah blah blah");
string another_string = DoSomethingElse(&some_string);

il y a une claire prise d'adresse.

Oublier la "règle" ou oublier les lambda, et consort ?

a "règle"

[Luc Hermitte]

a- un C majuscule devant les nom de Classe type CClass (reste de Visual studio)
b- le préfixe p_ pour les paramètres
c- une majuscule en début de nom de fonctions, et méthodes
d- une minuscule en début de variables et attributs
e- une entête avec les auteur, nom et rôle du fichier ainsi qu'un historique du fichier
f- une entête avec nom et rôle de chaque fonction dans les points cpp

a- Cette convention est idiote (désolé si mon terme peut choquer, mais c'est le cas). Ca ne marche pas quand on commence à remplacer les types natifs par des types plus sécurisés. Genre un entier, devient un entier qui cycle à 42 (i.e. CyclicInt<42> i = 40; assert(i++ == 0); ).
De plus, cela n'apporte strictement rien. Avec les types nous sommes dans un monde fortement typé. On ne pourra pas passer une fonction à un type comme cela.
Sans parler que l'immense majorité des types que l'on manipule ne sont pas des types primitifs. Quel besoin que de les préfixer ?
Et quid des arguments templates qui peuvent être des types primitifs comme des agrégats POD ou classe (au passage, ne pas oublier que struct et class, c'est quasi pareil pour le compilo).
(Enfin, il y a pire : préfixer les objets par des petits "o", là cela devient carrément stupide).
Ce sont des règles qui date d'un temps où des développeurs purement procéduraux (Pascal, C, ...) migraient vers le C++ alors qu'ils n'y étaient pas du tout à l'aise. Alors pour se rassurer au milieu de tous ces fourbes objets, ils leur donnaient des noms illisibles.

b- A éviter à cause d'une éventuelle confusion avec la Notation Hongroise Sys (qui elle également est à éviter) où le préfixage par p sert à désigner des pointeurs -- ce qui n'a pas grand intérêt dans un monde fortement typé.

c- Cela se fait en C#. Autour de moi, je vois plutôt de la lowerCamelCase pour les variables et fonctions, du UpperCamelCase pour les types.
Mais il ne faut pas oublier que le standard et son rejeton (boost) utilisent la snake_case.

e- Copyright et licence sont importants. On peut aussi mettre les auteurs en précisant les années et qui a fait quoi (dans les très grandes lignes). C'est un droit que nous avons même si le copyright est cédé à nos employeurs.
Pour l'historique, les gestionnaires de sources sont là pour nous aider.

f- Je fais du doxygen dans les .h pour centraliser en général. Et surtout pour la partie contrat, les exceptions, ou pour expliciter des détails sur les paramètres et les conséquences de l'appel à la fonction. Et aussi pour regrouper les types et fonctions libres en modules cohérents une fois la doc générée.

-----------
Concernant google et le pas d'exceptions, ils le justifient par "notre base de code historique est trop importante pour corriger le tir". Un peu comme Qt j'ai envie de dire.

[jo_link_noir]

Dans la même veine, il y a le style d'écriture des sources.

Depuis quelque temps je réduis l'espace horizontal. Pas que les lignes trop longue me dérange mais parce qu'il met plus simple de lire une source de bas en haut plutôt que bas/gauche -> haut/droit.
Au final je me retrouve avec beaucoup de lignes courtes, la plupart ne dépasse pas 30 caractères. Par contre je ne m'y sous toujours pas habitué et j’hésite encore sur certains aspects :/.

Par exemple avec un bout de code
Avant:

Code :

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

1
2
3
4
template<class CharT, class Traits>
std::ios_base::iostate
get_file_contents(std::string const & name, std::basic_streambuf<CharT, Traits> * sbout)
{ return get_file_contents(name.c_str(), sbout); }

Après:

Code :

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
template<
  class CharT
, class Traits
>
std::ios_base::iostate
get_file_contents(
  std::string const & name
, std::basic_streambuf<CharT, Traits> * sbout)
{
  return
  get_file_contents(
    name.c_str()
  , sbout);
}

J'imagine que chacun y va de son propre style, se serait sympa d'en parler aussi .

[Iradrille]

Je trouve la première forme trop compressée, la deuxième inutilement longue.
(Mais je suis habitué à des lignes relativement longues.)

Pour ton exemple, je l'aurai écrit comme ça

Code :

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

1
2
3
4
5
6
7
template <class CharT, class Traits>
std::ios_base::iostate get_file_contents(
	std::string const& name,
	std::basic_streambuf<CharT, Traits>* sbout)
{
	return get_file_contents(name.c_str(), sbout);
}

Mais pour une fonction avec un prototype plus court, j'aurais eu

Code :

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

1
2
3
4
template <class CharT, class Traits>
std::ios_base::iostate get_file_contents(std::string const& name, std::basic_streambuf<CharT, Traits>* sbout) {
	return get_file_contents(name.c_str(), sbout);
}

Je trouve important de toujours pouvoir identifier clairement les blocs de codes : j'utilise toujours des { } et toujours sur plusieurs lignes

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
int foo(int arg) {
	if(arg == 12) {
		return 0;
	}
	return arg;
 
	// ou eventuellement, dans les cas simples comme ici
	return arg == 12 ? 0: arg;
 
	// mais jamais
	if(arg == 12) return 0;
	return arg;
 
	// ni
	if(arg == 12) { return 0; }
	else { return arg; }
}
 
struct Foo {
	int attr;
	explicit Foo(int a): attr(a) { } // la seule exception : un bloc vide
};

Puisque le sujet va arriver : "tabs vs espaces ?". Pour ma part je supporte pas l'indentation avec des espaces, les tabs c'est cool et tout le monde peut régler son ide/éditeur pour leur donner la largeur désirée.

[jo_link_noir]

Je trouve la première forme trop compressée, la deuxième inutilement longue.
(Mais je suis habitué à des lignes relativement longues.)

Pareil C'est pour ça que je n'arrive pas à m'y faire...

À vrai dire, j'ai accentué l'effet avant de poster, mais ça à du être ainsi une heure ou deux. La forme actuelle étant :

Code :

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

1
2
3
4
5
6
template<class CharT, class Traits>
std::ios_base::iostate
get_file_contents(
  std::string const & name
, std::basic_streambuf<CharT, Traits> * sbout)
{ return get_file_contents(name.c_str(), sbout); }

Éventuellement, le paramètre est sur la même ligne que le nom de la fonction.

Je trouve important de toujours pouvoir identifier clairement les blocs de codes : j'utilise toujours des { } et toujours sur plusieurs lignes.

Je le fait aussi sauf que je mets sur une seule ligne les lambdas courtes et le corps des fonctions d'une ligne. Par contre même vide je met à la ligne.

J'initialise aussi une variable par ligne même dans la liste d'initialisation

Code :

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

1
2
3
4
5
6
7
8
struct Foo {
	int attr;
	int attr2;
	explicit Foo(int a, int b)
        : attr(a)
        , attr2(b)
        { }
};

Puisque le sujet va arriver : "tabs vs espaces ?". Pour ma part je supporte pas l'indentation avec des espaces, les tabs c'est cool et tout le monde peut régler son ide/éditeur pour leur donner la largeur désirée.

Avant je pensé comme toi. Et puis à force de voir les sources en console sur github et les forums avec des tabulations de 8 espaces j'en ai eu ras le bol (je ne sais pas comment le configurer). Le gros problème venait du fait que j’alignais les paramètres avec la parenthèse quand la ligne était trop grande

Code :

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

1
2
foo(premier_argument_extrêmement_long,
    second_argument_extrêmement_long);

Et varier la taille des tabulations donne un aspect désagréable qui s’accentue avec le nombre de tabulation.

Code :

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

1
2
foo(premier_argument_extrêmement_long,
        second_argument_extrêmement_long);

Vous avez vos propres règles pour les includes et la déclaration d'attributs ?

Pour les headers
- les miens
- les bibliothèques (dans un ordre plus moins définit selon le domaine de spécialisation avec le projet)
- boost
- std

Les miens au début pour empêcher la compilation s'il manque des headers qui serait inclut après par d'autres fichiers.

Pour les attributs, au début si sémantique de valeur, en bas si sémantique d’entité.

[Jean-Marc.Bourguet]

Puisque le sujet va arriver : "tabs vs espaces ?". Pour ma part je supporte pas l'indentation avec des espaces, les tabs c'est cool et tout le monde peut régler son ide/éditeur pour leur donner la largeur désirée.

D'après mon expérience, ça ne marche jamais et on finit plus ou moins rapidement à avoir du code qui n'est plus affiché correctement quelle que soit la valeur choisie si effectivement il y a des gens qui utilisent des largeurs différentes (Espaces "cachés" par les tabs qui ne le sont plus quand on change la largeur, utilisation des tabulations pour aligner -- même chez ceux qui prétendent faire correctement la différence -- ce qui fait qu'il n'y a plus d'alignement quand on change la largeur, ...) à moins qu'il y ait dans l'équipe quelqu'un affligé d'un TOC qui passe son temps à tout corriger. C'est un peu plus vivable si on a un style qui interdit l'alignement, il suffit alors d'avoir un programme qui fait la correction.

En passant, comme on utilise toujours quelque part un outil qui ne permet pas de choisir autre chose que 8 comme largeur de tab (merge, navigateur de code de l'outil de gestion de version, outil de revue de code, ...), c'est la seule qui est utilisable.

[Iradrille]

Et puis à force de voir les sources en console sur github et les forums avec des tabulations de 8 espaces j'en ai eu ras le bol (je ne sais pas comment le configurer).

Avec ff sous Windows, il suffit de rajouter un fichier "userContent.css" contenant pre { -moz-tab-size: 4!important; } dans C:/Users/[nom d user]/AppData/Roaming/Mozilla/Firefox/Profiles/[nom de profile]/chrome, ça doit être plus ou moins identiques avec les autres navigateurs, et pour Linux, je fichier doit juste être caché autre part.

Le gros problème venait du fait que j’alignais les paramètres avec la parenthèse quand la ligne était trop grande.
Et varier la taille des tabulations donne un aspect désagréable qui s’accentue avec le nombre de tabulation.

D'après mon expérience, ça ne marche jamais et on finit plus ou moins rapidement à avoir du code qui n'est plus affiché correctement quelle que soit la valeur choisie si effectivement il y a des gens qui utilisent des largeurs différentes (Espaces "cachés" par les tabs qui ne le sont plus quand on change la largeur, utilisation des tabulations pour aligner -- même chez ceux qui prétendent faire correctement la différence -- ce qui fait qu'il n'y a plus d'alignement quand on change la largeur, ...) à moins qu'il y ait dans l'équipe quelqu'un affligé d'un TOC qui passe son temps à tout corriger. C'est un peu plus vivable si on a un style qui interdit l'alignement, il suffit alors d'avoir un programme qui fait la correction.

Ce sont deux problèmes que j'évite de la manière la plus simple possible : je n'aligne pas. Pour les arguments d'une fonction (ou une grande condition dans un if, etc...), je vais à la ligne et rajoute un tab.
Pour les constantes, pareil que ce soit aligné ou pas ne me dérange pas.

Code :

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

1
2
3
4
5
 enum {
	CONSTANTE = 0x00,
	CONSTANTE_PLUS_LONGUE = 0x0a,
	CONSTANTE_2 = 0x42
};

Mais c'est effectivement un problème si c'est aligné à coup de tabs.

En passant, comme on utilise toujours quelque part un outil qui ne permet pas de choisir autre chose que 8 comme largeur de tab (merge, navigateur de code de l'outil de gestion de version, outil de revue de code, ...), c'est la seule qui est utilisable.

La dessus tu marques un point.

Il reste toujours la solution de remplacer les espaces par des tabs (ou inversement) quand on pull, et de faire l'inverse quand on commit. Ça marche pour le remplacement des fins de lignes, ya pas de raisons que ça ne marche pas pour ça.

[Trademark]

Dommage que toutes ces consignes ne soient pas justifiée par un petit texte.

Tout est justifié ;-) Il suffit de cliquer sur la flèche.

[Neckara]

Tout est justifié ;-) Il suffit de cliquer sur la flèche.

Je croyais que c'était des puces