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
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Coding Style</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="appendix_contributing.html" title="Appendix A. Contributing" /><link rel="prev" href="bk01apas02.html" title="Directory Layout and Source Conventions" /><link rel="next" href="bk01apas04.html" title="Documentation Style" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Coding Style</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01apas02.html">Prev</a> </td><th width="60%" align="center">Appendix A. Contributing</th><td width="20%" align="right"> <a accesskey="n" href="bk01apas04.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="contrib.coding_style"></a>Coding Style</h2></div></div></div><p>
</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="coding_style.bad_identifiers"></a>Bad Identifiers</h3></div></div></div><p>
Identifiers that conflict and should be avoided.
</p><div class="literallayout"><p><br />
This is the list of names “<span class="quote">reserved to the<br />
implementation</span>” that have been claimed by certain<br />
compilers and system headers of interest, and should not be used<br />
in the library. It will grow, of course. We generally are<br />
interested in names that are not all-caps, except for those like<br />
"_T"<br />
<br />
For Solaris:<br />
_B<br />
_C<br />
_L<br />
_N<br />
_P<br />
_S<br />
_U<br />
_X<br />
_E1<br />
..<br />
_E24<br />
<br />
Irix adds:<br />
_A<br />
_G<br />
<br />
MS adds:<br />
_T<br />
<br />
BSD adds:<br />
__used<br />
__unused<br />
__inline<br />
_Complex<br />
__istype<br />
__maskrune<br />
__tolower<br />
__toupper<br />
__wchar_t<br />
__wint_t<br />
_res<br />
_res_ext<br />
__tg_*<br />
<br />
SPU adds:<br />
__ea<br />
<br />
For GCC:<br />
<br />
[Note that this list is out of date. It applies to the old<br />
name-mangling; in G++ 3.0 and higher a different name-mangling is<br />
used. In addition, many of the bugs relating to G++ interpreting<br />
these names as operators have been fixed.]<br />
<br />
The full set of __* identifiers (combined from gcc/cp/lex.c and<br />
gcc/cplus-dem.c) that are either old or new, but are definitely <br />
recognized by the demangler, is:<br />
<br />
__aa<br />
__aad<br />
__ad<br />
__addr<br />
__adv<br />
__aer<br />
__als<br />
__alshift<br />
__amd<br />
__ami<br />
__aml<br />
__amu<br />
__aor<br />
__apl<br />
__array<br />
__ars<br />
__arshift<br />
__as<br />
__bit_and<br />
__bit_ior<br />
__bit_not<br />
__bit_xor<br />
__call<br />
__cl<br />
__cm<br />
__cn<br />
__co<br />
__component<br />
__compound<br />
__cond<br />
__convert<br />
__delete<br />
__dl<br />
__dv<br />
__eq<br />
__er<br />
__ge<br />
__gt<br />
__indirect<br />
__le<br />
__ls<br />
__lt<br />
__max<br />
__md<br />
__method_call<br />
__mi<br />
__min<br />
__minus<br />
__ml<br />
__mm<br />
__mn<br />
__mult<br />
__mx<br />
__ne<br />
__negate<br />
__new<br />
__nop<br />
__nt<br />
__nw<br />
__oo<br />
__op<br />
__or<br />
__pl<br />
__plus<br />
__postdecrement<br />
__postincrement<br />
__pp<br />
__pt<br />
__rf<br />
__rm<br />
__rs<br />
__sz<br />
__trunc_div<br />
__trunc_mod<br />
__truth_andif<br />
__truth_not<br />
__truth_orif<br />
__vc<br />
__vd<br />
__vn<br />
<br />
SGI badnames:<br />
__builtin_alloca<br />
__builtin_fsqrt<br />
__builtin_sqrt<br />
__builtin_fabs<br />
__builtin_dabs<br />
__builtin_cast_f2i<br />
__builtin_cast_i2f<br />
__builtin_cast_d2ll<br />
__builtin_cast_ll2d<br />
__builtin_copy_dhi2i<br />
__builtin_copy_i2dhi<br />
__builtin_copy_dlo2i<br />
__builtin_copy_i2dlo<br />
__add_and_fetch<br />
__sub_and_fetch<br />
__or_and_fetch<br />
__xor_and_fetch<br />
__and_and_fetch<br />
__nand_and_fetch<br />
__mpy_and_fetch<br />
__min_and_fetch<br />
__max_and_fetch<br />
__fetch_and_add<br />
__fetch_and_sub<br />
__fetch_and_or<br />
__fetch_and_xor<br />
__fetch_and_and<br />
__fetch_and_nand<br />
__fetch_and_mpy<br />
__fetch_and_min<br />
__fetch_and_max<br />
__lock_test_and_set<br />
__lock_release<br />
__lock_acquire<br />
__compare_and_swap<br />
__synchronize<br />
__high_multiply<br />
__unix<br />
__sgi<br />
__linux__<br />
__i386__<br />
__i486__<br />
__cplusplus<br />
__embedded_cplusplus<br />
// long double conversion members mangled as __opr<br />
// http://gcc.gnu.org/ml/libstdc++/1999-q4/msg00060.html<br />
_opr<br />
</p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="coding_style.example"></a>By Example</h3></div></div></div><div class="literallayout"><p><br />
This library is written to appropriate C++ coding standards. As such,<br />
it is intended to precede the recommendations of the GNU Coding<br />
Standard, which can be referenced in full here:<br />
<br />
http://www.gnu.org/prep/standards/standards.html#Formatting<br />
<br />
The rest of this is also interesting reading, but skip the "Design<br />
Advice" part.<br />
<br />
The GCC coding conventions are here, and are also useful:<br />
http://gcc.gnu.org/codingconventions.html<br />
<br />
In addition, because it doesn't seem to be stated explicitly anywhere<br />
else, there is an 80 column source limit.<br />
<br />
ChangeLog entries for member functions should use the<br />
classname::member function name syntax as follows:<br />
<br />
1999-04-15 Dennis Ritchie <dr@att.com><br />
<br />
* src/basic_file.cc (__basic_file::open): Fix thinko in<br />
_G_HAVE_IO_FILE_OPEN bits.<br />
<br />
Notable areas of divergence from what may be previous local practice<br />
(particularly for GNU C) include:<br />
<br />
01. Pointers and references<br />
char* p = "flop";<br />
char& c = *p;<br />
-NOT-<br />
char *p = "flop"; // wrong<br />
char &c = *p; // wrong<br />
<br />
Reason: In C++, definitions are mixed with executable code. Here, <br />
p is being initialized, not *p. This is near-universal<br />
practice among C++ programmers; it is normal for C hackers<br />
to switch spontaneously as they gain experience.<br />
<br />
02. Operator names and parentheses<br />
operator==(type)<br />
-NOT-<br />
operator == (type) // wrong<br />
<br />
Reason: The == is part of the function name. Separating<br />
it makes the declaration look like an expression. <br />
<br />
03. Function names and parentheses<br />
void mangle()<br />
-NOT-<br />
void mangle () // wrong<br />
<br />
Reason: no space before parentheses (except after a control-flow<br />
keyword) is near-universal practice for C++. It identifies the<br />
parentheses as the function-call operator or declarator, as <br />
opposed to an expression or other overloaded use of parentheses.<br />
<br />
04. Template function indentation<br />
template<typename T><br />
void <br />
template_function(args)<br />
{ }<br />
-NOT-<br />
template<class T><br />
void template_function(args) {};<br />
<br />
Reason: In class definitions, without indentation whitespace is<br />
needed both above and below the declaration to distinguish<br />
it visually from other members. (Also, re: "typename"<br />
rather than "class".) T often could be int, which is <br />
not a class. ("class", here, is an anachronism.)<br />
<br />
05. Template class indentation<br />
template<typename _CharT, typename _Traits><br />
class basic_ios : public ios_base<br />
{<br />
public:<br />
// Types:<br />
};<br />
-NOT-<br />
template<class _CharT, class _Traits><br />
class basic_ios : public ios_base<br />
{<br />
public:<br />
// Types:<br />
};<br />
-NOT-<br />
template<class _CharT, class _Traits><br />
class basic_ios : public ios_base<br />
{<br />
public:<br />
// Types:<br />
};<br />
<br />
06. Enumerators<br />
enum<br />
{<br />
space = _ISspace,<br />
print = _ISprint,<br />
cntrl = _IScntrl<br />
};<br />
-NOT-<br />
enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl };<br />
<br />
07. Member initialization lists<br />
All one line, separate from class name.<br />
<br />
gribble::gribble() <br />
: _M_private_data(0), _M_more_stuff(0), _M_helper(0);<br />
{ }<br />
-NOT-<br />
gribble::gribble() : _M_private_data(0), _M_more_stuff(0), _M_helper(0);<br />
{ }<br />
<br />
08. Try/Catch blocks<br />
try <br />
{<br />
//<br />
} <br />
catch (...)<br />
{<br />
//<br />
} <br />
-NOT-<br />
try {<br />
// <br />
} catch(...) { <br />
//<br />
}<br />
<br />
09. Member functions declarations and definitions<br />
Keywords such as extern, static, export, explicit, inline, etc<br />
go on the line above the function name. Thus<br />
<br />
virtual int <br />
foo()<br />
-NOT-<br />
virtual int foo()<br />
<br />
Reason: GNU coding conventions dictate return types for functions<br />
are on a separate line than the function name and parameter list<br />
for definitions. For C++, where we have member functions that can<br />
be either inline definitions or declarations, keeping to this<br />
standard allows all member function names for a given class to be<br />
aligned to the same margin, increasing readability.<br />
<br />
<br />
10. Invocation of member functions with "this->"<br />
For non-uglified names, use this->name to call the function.<br />
<br />
this->sync()<br />
-NOT-<br />
sync()<br />
<br />
Reason: Koenig lookup.<br />
<br />
11. Namespaces<br />
namespace std<br />
{<br />
blah blah blah;<br />
} // namespace std<br />
<br />
-NOT-<br />
<br />
namespace std {<br />
blah blah blah;<br />
} // namespace std<br />
<br />
12. Spacing under protected and private in class declarations:<br />
space above, none below<br />
i.e.<br />
<br />
public:<br />
int foo;<br />
<br />
-NOT-<br />
public:<br />
<br />
int foo;<br />
<br />
13. Spacing WRT return statements.<br />
no extra spacing before returns, no parenthesis<br />
i.e.<br />
<br />
}<br />
return __ret;<br />
<br />
-NOT-<br />
}<br />
<br />
return __ret;<br />
<br />
-NOT-<br />
<br />
}<br />
return (__ret);<br />
<br />
<br />
14. Location of global variables.<br />
All global variables of class type, whether in the "user visible"<br />
space (e.g., cin) or the implementation namespace, must be defined<br />
as a character array with the appropriate alignment and then later<br />
re-initialized to the correct value.<br />
<br />
This is due to startup issues on certain platforms, such as AIX.<br />
For more explanation and examples, see src/globals.cc. All such<br />
variables should be contained in that file, for simplicity.<br />
<br />
15. Exception abstractions<br />
Use the exception abstractions found in functexcept.h, which allow<br />
C++ programmers to use this library with -fno-exceptions. (Even if<br />
that is rarely advisable, it's a necessary evil for backwards<br />
compatibility.)<br />
<br />
16. Exception error messages<br />
All start with the name of the function where the exception is<br />
thrown, and then (optional) descriptive text is added. Example:<br />
<br />
__throw_logic_error(__N("basic_string::_S_construct NULL not valid"));<br />
<br />
Reason: The verbose terminate handler prints out exception::what(),<br />
as well as the typeinfo for the thrown exception. As this is the<br />
default terminate handler, by putting location info into the<br />
exception string, a very useful error message is printed out for<br />
uncaught exceptions. So useful, in fact, that non-programmers can<br />
give useful error messages, and programmers can intelligently<br />
speculate what went wrong without even using a debugger.<br />
<br />
17. The doxygen style guide to comments is a separate document,<br />
see index.<br />
<br />
The library currently has a mixture of GNU-C and modern C++ coding<br />
styles. The GNU C usages will be combed out gradually.<br />
<br />
Name patterns:<br />
<br />
For nonstandard names appearing in Standard headers, we are constrained <br />
to use names that begin with underscores. This is called "uglification".<br />
The convention is:<br />
<br />
Local and argument names: __[a-z].*<br />
<br />
Examples: __count __ix __s1 <br />
<br />
Type names and template formal-argument names: _[A-Z][^_].*<br />
<br />
Examples: _Helper _CharT _N <br />
<br />
Member data and function names: _M_.*<br />
<br />
Examples: _M_num_elements _M_initialize ()<br />
<br />
Static data members, constants, and enumerations: _S_.*<br />
<br />
Examples: _S_max_elements _S_default_value<br />
<br />
Don't use names in the same scope that differ only in the prefix, <br />
e.g. _S_top and _M_top. See BADNAMES for a list of forbidden names.<br />
(The most tempting of these seem to be and "_T" and "__sz".)<br />
<br />
Names must never have "__" internally; it would confuse name<br />
unmanglers on some targets. Also, never use "__[0-9]", same reason.<br />
<br />
--------------------------<br />
<br />
[BY EXAMPLE]<br />
<br />
#ifndef _HEADER_<br />
#define _HEADER_ 1<br />
<br />
namespace std<br />
{<br />
class gribble<br />
{<br />
public:<br />
gribble() throw();<br />
<br />
gribble(const gribble&);<br />
<br />
explicit <br />
gribble(int __howmany);<br />
<br />
gribble& <br />
operator=(const gribble&);<br />
<br />
virtual <br />
~gribble() throw ();<br />
<br />
// Start with a capital letter, end with a period.<br />
inline void <br />
public_member(const char* __arg) const;<br />
<br />
// In-class function definitions should be restricted to one-liners.<br />
int <br />
one_line() { return 0 }<br />
<br />
int <br />
two_lines(const char* arg) <br />
{ return strchr(arg, 'a'); }<br />
<br />
inline int <br />
three_lines(); // inline, but defined below.<br />
<br />
// Note indentation.<br />
template<typename _Formal_argument><br />
void <br />
public_template() const throw();<br />
<br />
template<typename _Iterator><br />
void <br />
other_template();<br />
<br />
private:<br />
class _Helper;<br />
<br />
int _M_private_data;<br />
int _M_more_stuff;<br />
_Helper* _M_helper;<br />
int _M_private_function();<br />
<br />
enum _Enum <br />
{ <br />
_S_one, <br />
_S_two <br />
};<br />
<br />
static void <br />
_S_initialize_library();<br />
};<br />
<br />
// More-or-less-standard language features described by lack, not presence.<br />
# ifndef _G_NO_LONGLONG<br />
extern long long _G_global_with_a_good_long_name; // avoid globals!<br />
# endif<br />
<br />
// Avoid in-class inline definitions, define separately;<br />
// likewise for member class definitions:<br />
inline int<br />
gribble::public_member() const<br />
{ int __local = 0; return __local; }<br />
<br />
class gribble::_Helper<br />
{<br />
int _M_stuff;<br />
<br />
friend class gribble;<br />
};<br />
}<br />
<br />
// Names beginning with "__": only for arguments and<br />
// local variables; never use "__" in a type name, or<br />
// within any name; never use "__[0-9]".<br />
<br />
#endif /* _HEADER_ */<br />
<br />
<br />
namespace std <br />
{<br />
template<typename T> // notice: "typename", not "class", no space<br />
long_return_value_type<with_many, args> <br />
function_name(char* pointer, // "char *pointer" is wrong.<br />
char* argument, <br />
const Reference& ref)<br />
{<br />
// int a_local; /* wrong; see below. */<br />
if (test) <br />
{ <br />
nested code <br />
}<br />
<br />
int a_local = 0; // declare variable at first use.<br />
<br />
// char a, b, *p; /* wrong */<br />
char a = 'a';<br />
char b = a + 1;<br />
char* c = "abc"; // each variable goes on its own line, always.<br />
<br />
// except maybe here...<br />
for (unsigned i = 0, mask = 1; mask; ++i, mask <<= 1) {<br />
// ...<br />
}<br />
}<br />
<br />
gribble::gribble()<br />
: _M_private_data(0), _M_more_stuff(0), _M_helper(0);<br />
{ }<br />
<br />
inline int <br />
gribble::three_lines()<br />
{<br />
// doesn't fit in one line.<br />
}<br />
} // namespace std<br />
</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01apas02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix_contributing.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01apas04.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Directory Layout and Source Conventions </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Documentation Style</td></tr></table></div></body></html>
|
