summaryrefslogtreecommitdiff
path: root/d/dev/standards/coding.txt
blob: ac6bd4e057d2a02eb274755dc05f303fd2b029dd (plain)
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
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
*Title: Coding standards Efrei Robotique
*Author: Ni

*TOC

* Intro

Afin d'assurer un code source homog�ne, ce document d�fini les standards de
codage pour tout programme d�velopp� pour Efrei Robotique. Le but n'est pas de
d�finir un standard parfait, aucun ne peu pr�tendre l'�tre, mais un standard
homog�ne.

Il est bas� sur les
[GNU Coding Standards (http://www.gnu.org/prep/standards.html)].

Ce document n'est pas fig�e, si vous n'�tes pas d'accord avec un point, on
peut en discuter.

* Code C

** Formatage

L'indentation est de 4 caract�res, tout en gardant une tabulation de 8
caract�res. �viter de faire des lignes de plus de 78 caract�res.

Pour les fonctions mettre le nom de la fonction et les accolades en premi�re
colonne.

Aligner les lignes cass�es avec les parenth�ses ou les op�rateurs.

Les accolades de blocs sont mis sur leur propre ligne et d�cal�es 2
caract�res.

Mettre un espace autour des op�rateurs sauf :

	* pour le |--|, le |++| et |->| ;
	* apr�s les op�rateurs d'indirection ;
	* avant une virgule ;
	* apr�s une parenth�se ouvrante ou avant une parenth�se fermante.

Les identifiant sont �crits en minuscule, les mots s�par�s par un caract�re
de soulignement (|_|). La seule exception est les noms de macros �crits en
majuscules. Un identifiant de type se termine par |_t| (c'est �ventuellement
discutable... mais bon, je trouve que c'est pas mal).

Un exemple pour faire plus clair :

^<<
static char *
concat (char *s1, char *s2)
{
    int i;
    if (!s1 || !s2)
	return 0;
    for (i = 0; i < 5; i++)
      {
	faire_un_truc_complexe (avec_un_long_argument,
				et_un_autre[4] + 1,
				toto ());
      }
    do
      {
	z--;
      } while (truc ());
    return 0;
}
^>>

Lorsque l'on coupe une expression sur plusieurs lignes essayer de couper avant
l'op�rateur.

�viter d'utiliser NULL, c'est pour les vieux. Utilisez 0 � la place.

Il n'y a jamais plus de deux espaces � la suite, sauf pour l'indentation. Il
n'y a pas d'espace en fin de ligne.

On saute une ligne apr�s chaque fonction m�me la derni�re, mais jamais �
l'int�rieur d'une fonction. Si l'envie vous prend de mettre une ligne vide
dans une fonction, c'est qu'on pourrait certainement la remplacer par un
commentaire.

Il n'y a jamais deux ligne vides � la suite.

** Commentaires.

Une phrase commence par une majuscule et se termine par un point. En fran�ais,
il y a un espace avant chaque ponctuation compos� de deux signes, mais pas
d'un ou trois signes. En anglais il n'y a pas d'espace devant un caract�re de
ponctuation, mais deux espaces apr�s un point s'il signifie une fin de phrase.

Placez les commentaires sur leur propre ligne rarement en fin de ligne sauf
�ventuellement pour la description d'une structure ou d'une palanqu�e de
variables globales (mais si, pour un microcontr�leur, c'est bien).

Les seuls commentaires autoris�s en C sont les :

	/* Commentaires. */

On peut utiliser toutefois les commentaires C++ pour commenter temporairement
du code.

Si le commentaire prend plusieurs lignes le formater de cette mani�re :

	/* Ceci
	 * est
	 * un long
	 * commentaire. */

Merci de mettre plein de commentaires, mais uniquement s'il apporte
quelquechose. Par exemple :

^<<
/* Initialise i (mauvais commentaire). */
i = 0;
/* Recherche la fin de la liste (bon commentaire). */
for (l = debut; l != fin; l = l->next)
    ;
^>>

Mettre un commentaire au d�but de chaque fonction afin d'expliquer � qui elle
sert. Ne pas r�p�ter dans le commentaire ce qui est d�j� dit dans la
d�claration de la fonction.

Chaque fichier a une structure normalis�e.

Pour un en-t�te |robert.h| :

^<<
#ifndef ROBERT_H
#define ROBERT_H
/* robert.h - Fonctions de robertisation des param�tres. */
/* Programme de simulation de merguez. {{{
 *
 * Copyright (C) 2004 Nicolas Schodet
 *
 * Robot APB Team/Efrei 2005.
 *        Web: http://assos.efrei.fr/robot/
 *      Email: robot AT efrei DOT fr
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * 
 * This program 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 General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 *
 * }}} */
#include "entete_non_systeme.h"

#include <entete_systeme.h>

{Ici les d�finitions de types et de structures.}

/* +AutoDec */
{Ici, les d�finitions de fonctions ins�r�es automatiquement.}
/* -AutoDec */

#endif /* ROBERT_H */
^>>

Pour un code source |robert.c| :

^<<
/* robert.c - Fonctions de robertisation des param�tres. */
/* Programme de simulation de merguez. {{{
 *
 * Copyright (C) 2004 Nicolas Schodet
 *
 * Robot APB Team/Efrei 2005.
 *        Web: http://assos.efrei.fr/robot/
 *      Email: robot AT efrei DOT fr
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * 
 * This program 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 General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 *
 * }}} */
#include "robert.h"
#include "entete_non_systeme.h"

#include <entete_systeme.h>

{Ici les d�finitions de types et de structures locales au fichier.}

/* +AutoDec */
{Ici, les d�finitions de fonctions statiques ins�r�es automatiquement.}
/* -AutoDec */

{Ici, les d�finitions de variables statiques ou globales.}

{Ici, les d�finitions des fonctions.}
^>>

Cette documentation est fournie avec les fichiers de template et le script qui
va avec pour Vim.

** Extractdoc

Pour les petits programmes en C, |extractdoc| permet d'extraire la doc des codes
sources. Il utilise le m�me style de commentaires que doxygen, c'est � dire :

	/** Ceci est un commentaire extractdoc. */

Il n'utilise par contre pas les balises doxygen, je trouve qu'elles nuisent �
la lecture du commentaire. Il reconna�t par contre la syntaxe
[aft (http://www.maplefish.com/todd/aft-refman.html)], si aft est utilis� pour
transformer le texte. En pratique, il remplace un espace en d�but de
commentaire par une tabulation et fait aussi le remplacement de liste de
description. Par exemple :

^<<
/**
 * Met � jour les informations de cuisson.
 *
 *  - t : temp�rature (�C).
 *  - mode : type de cuisson.
 */
^>>

donne :

^<<
Met � jour les informations de cuisson.

	[t] temp�rature (�C).
	[mode] type de cuisson.
^>>

et dans aft :

Met � jour les informations de cuisson.

	[t] temp�rature (�C).
	[mode] type de cuisson.

** Trucs et astuces

�vitez d'utiliser des unsigned long ou des short, on ne devrais utiliser que :

	[des int] pour les entiers, m�me s'il sont toujours positifs ;
	[des double] pour les flottants ;
	[des char] pour des caract�res ;
	[des unsigned char] pour des donn�es binaires.

* Code C++

** Formatage

Les r�gles du formatage du code C s'appliquent.

Vim ne g�re pas encore correctement l'indentation de certain aspects du C++, notamment :

	* les namespaces ;
	* les listes d'initialisations.

Pour les namespaces, n'indentez pas le contenu, c'est inutile d'indenter un
fichier complet. Fermez toujours un namespace avec un commentaire rapellant le
nom du namespace.

Pour les listes d'initialisation, on les formate de cette mani�re :

^<<
/// Constructeur par d�faut.
Merguez::Merguez (void)
    : temperatureDeCuisson_ (0), identificateur_tres_long_ (42),
      un_autre_encore_ (51), fermete_ (0.0)
{
}
^>>

Les identificateurs sont �crit en minuscule. Les mots sont s�par�s par une
majuscule. Les noms de types commencent par une majuscule. Les noms de
variables membres priv�es ou prot�g�es se terminent par un caract�re de
soulignement (|_|).

Un petit exemple :

^<<
namespace bbq
{

/// Classe de d�finition des propri�t�s d'une merguez.
class Merguez
{
    int temperatureDeCuisson_;
    double fermete_;
  public:
    /// Constructeur par d�faut.
    Merguez (void);
};

} // bbq
^>>

L'ordre des d�clarations dans la classe est le suivant (avec variations
possibles) :

	* types ;
	* variables membres ;
	* constructeurs ;
	* constructeur de recopie, destructeur et operateur= ;
	* fonctions publiques ;
	* fonctions priv�es ou prot�g�es.

Si les constructeurs ou destructeurs sont priv�es, ils n'occupent plus la
position de t�te de classe. Les d�finitions dans le fichier |.cc| suivent le
m�me ordre que la d�claration.

Les classes sont d�clar�es dans un fichier |.h| de la forme :

^<<
#ifndef MERGUEZ_H
#define MERGUEZ_H
// merguez.h - Composant Merguez.
// Programme de barbeq. {{{
//
// Copyright (C) 2004 Nicolas Schodet
//
// Robot APB Team/Efrei 2005.
//        Web: http://assos.efrei.fr/robot/
//      Email: robot AT efrei DOT fr
//
// This program is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation; either version 2 of the License, or
// (at your option) any later version.
// 
// This program 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 General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
//
// }}}
#include "entete_non_systeme.h"

#include <entete_systeme.h>

{Ici la d�finition de classe.}

{Ici la d�claration de fonctions globales.}

{Ici la d�finition de fonctions inlines.}

#endif // MERGUEZ_H
^>>

Les classes sont impl�ment�es dans un fichier |.cc| de la forme :

^<<
// merguez.cc - Composant Merguez.
// Programme de barbeq. {{{
//
// Copyright (C) 2004 Nicolas Schodet
//
// Robot APB Team/Efrei 2005.
//        Web: http://assos.efrei.fr/robot/
//      Email: robot AT efrei DOT fr
//
// This program is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation; either version 2 of the License, or
// (at your option) any later version.
// 
// This program 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 General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
//
// }}}
#include "merguez.h"
#include "entete_non_systeme.h"

#include <entete_systeme.h>

{Ici les d�finitions de types et de structures locales au fichier.}

{Ici, les d�finitions de fonctions statiques.}

{Ici, les d�finitions de variables statiques ou globales.}

{Ici, les d�finitions des fonctions.}
^>>

Les noms de fichiers ne prennent jamais de majuscule.

** Commentaires.

Le seul type de commentaire � utiliser est le commentaire C++. On peut
toutefois utiliser le commentaire C pour d�sactiver temporairement du code.

La documentation du code se fait avec doxygen. On utilise les trois barres
obliques pour signifier � doxygen que ce commentaire doit �tre lu. On essayera
toutefois d'�viter les balises doxygen qui r�duisent la lisibilit� du
commentaire.

Une exception � la r�gle des commentaires bidons s'applique aux constructeurs
et destructeurs afin que chaque fonction ait son commentaire attitr�.

** Trucs et astuces

Dans une classe qui ne peut �tre copi�e, on peut d�clarer le constructeur de
recopie et l'op�rateur = comme fonction priv�es. Ce n'est alors pas la peine
de les d�finir.

Une variable de boucle peut �tre d�clar�e dans la d�finition de la boucle.

N'oubliez pas les |std::| pour acc�der � une classe de la biblioth�que
standard.

D�clarer comme fonction const toute fonction qui peut l'�tre si le sens le
justifie. De m�me d�clarer les param�tres par pointeur ou r�f�rence const si
possible. Dans le cas de conteneurs const, utiliser des |const_iterator|,
sinon, �a ne compile pas.

R�utilisez le code existant et fa�tes du code r�utilisable.

Initialisez toutes les variables membres � un �tat connu.

Usez et abuser des conteneurs standards comme les |std::list|, |std::vector|,
|std::map|, mais encore et surtout les |std::string|.

* Outils

** Vim

Voici les options pour vim � inclure dans le |.vimrc| :

^<<
" Les .h c'est du C, si vous faites du C.
" let c_syntax_for_h = 1

" Options de formatage
set cinoptions={.5s:.5sg.5sh.5st0(0=.5s

function! s:C_options()
   setlocal cindent
   let g:c_syntax_for_h = 1
   setlocal formatoptions+=rt
   setlocal shortmess-=T
   setlocal shiftwidth=4
endfunction

function! s:CPP_options()
   call s:C_options()
   let g:c_syntax_for_h = 0
   set fo-=o fo-=r
   set com-=:// com+=:///,://
endfunction

au FileType c call s:C_options()
au FileType cpp call s:CPP_options()

" Corrige un probl�me lors de la compilation dans plusieurs r�pertoire.
set errorformat=%*[^\"]\"%f\"%*\\D%l:\ %m,\"%f\"%*\\D%l:\ %m,%-G%f:%l:\ (Each\ undeclared\ identifier\ is\ reported\ only\ once,%-G%f:%l:\ for\ each\ function\ it\ appears\ in.),%f:%l:%m,\"%f\"\\,\ line\ %l%*\\D%c%*[^\ ]\ %m,%D%*\\a:\ Entering\ directory\ `%f',%X%*\\a:\ Leaving\ directory\ `%f',%DMaking\ %*\\a\ in\ %f
^>>

** G�n�rateur de templates pour Vim

Le r�pertoire ni_templates contient tout ce qu'il faut pour faire fonctionner
les templates. Il suffit de copier son contenu dans votre r�pertoire |.vim| et
d'ajouter au |.vimrc| :

^<<
let template_variant = "robot"

" Cr�e un nouveau fichier C/C++.
function! F_template()
   if &filetype == "c" && expand ("%") =~ ".h$"
      Template h
   elseif &filetype == "cpp" && (expand ("%") =~ ".h$" || expand ("%") =~ ".hh$" || expand ("%") =~ ".H$" || expand ("%") =~ ".hpp")
      Template hpp
   else
      Template
   endif
endfunction

au BufNewFile *.c,*.cc,*.h,*.hh,*.hpp,*.C,*.cxx call F_template()
^>>