1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <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-NS Stylesheets V1.76.1" /><meta name="keywords" content=" ISO C++ , library " /><meta name="keywords" content=" ISO C++ , runtime , library " /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="appendix_contributing.html" title="Appendix A. Contributing" /><link rel="prev" href="source_organization.html" title="Directory Layout and Source Conventions" /><link rel="next" href="source_design_notes.html" title="Design Notes" /></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="source_organization.html">Prev</a> </td><th width="60%" align="center">Appendix A.
6 </th><td width="20%" align="right"> <a accesskey="n" href="source_design_notes.html">Next</a></td></tr></table><hr /></div><div class="section" title="Coding Style"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="contrib.coding_style"></a>Coding Style</h2></div></div></div><p>
7 </p><div class="section" title="Bad Identifiers"><div class="titlepage"><div><div><h3 class="title"><a id="coding_style.bad_identifiers"></a>Bad Identifiers</h3></div></div></div><p>
8 Identifiers that conflict and should be avoided.
9 </p><div class="literallayout"><p><br />
10 This is the list of names <span class="quote">“<span class="quote">reserved to the<br />
11 implementation</span>”</span> that have been claimed by certain<br />
12 compilers and system headers of interest, and should not be used<br />
13 in the library. It will grow, of course. We generally are<br />
14 interested in names that are not all-caps, except for those like<br />
57 [Note that this list is out of date. It applies to the old<br />
58 name-mangling; in G++ 3.0 and higher a different name-mangling is<br />
59 used. In addition, many of the bugs relating to G++ interpreting<br />
60 these names as operators have been fixed.]<br />
62 The full set of __* identifiers (combined from gcc/cp/lex.c and<br />
63 gcc/cplus-dem.c) that are either old or new, but are definitely<br />
64 recognized by the demangler, is:<br />
130 __postdecrement<br />
131 __postincrement<br />
148 __builtin_alloca<br />
149 __builtin_fsqrt<br />
153 __builtin_cast_f2i<br />
154 __builtin_cast_i2f<br />
155 __builtin_cast_d2ll<br />
156 __builtin_cast_ll2d<br />
157 __builtin_copy_dhi2i<br />
158 __builtin_copy_i2dhi<br />
159 __builtin_copy_dlo2i<br />
160 __builtin_copy_i2dlo<br />
161 __add_and_fetch<br />
162 __sub_and_fetch<br />
164 __xor_and_fetch<br />
165 __and_and_fetch<br />
166 __nand_and_fetch<br />
167 __mpy_and_fetch<br />
168 __min_and_fetch<br />
169 __max_and_fetch<br />
170 __fetch_and_add<br />
171 __fetch_and_sub<br />
173 __fetch_and_xor<br />
174 __fetch_and_and<br />
175 __fetch_and_nand<br />
176 __fetch_and_mpy<br />
177 __fetch_and_min<br />
178 __fetch_and_max<br />
179 __lock_test_and_set<br />
182 __compare_and_swap<br />
184 __high_multiply<br />
191 __embedded_cplusplus<br />
192 // long double conversion members mangled as __opr<br />
193 // http://gcc.gnu.org/ml/libstdc++/1999-q4/msg00060.html<br />
195 </p></div></div><div class="section" title="By Example"><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 />
196 This library is written to appropriate C++ coding standards. As such,<br />
197 it is intended to precede the recommendations of the GNU Coding<br />
198 Standard, which can be referenced in full here:<br />
200 <a class="link" href="http://www.gnu.org/prep/standards/standards.html#Formatting" target="_top">http://www.gnu.org/prep/standards/standards.html#Formatting</a><br />
202 The rest of this is also interesting reading, but skip the "Design<br />
205 The GCC coding conventions are here, and are also useful:<br />
206 <a class="link" href="http://gcc.gnu.org/codingconventions.html" target="_top">http://gcc.gnu.org/codingconventions.html</a><br />
208 In addition, because it doesn't seem to be stated explicitly anywhere<br />
209 else, there is an 80 column source limit.<br />
211 <code class="filename">ChangeLog</code> entries for member functions should use the<br />
212 classname::member function name syntax as follows:<br />
214 <code class="code"><br />
215 1999-04-15 Dennis Ritchie <dr@att.com><br />
217 * src/basic_file.cc (__basic_file::open): Fix thinko in<br />
218 _G_HAVE_IO_FILE_OPEN bits.<br />
221 Notable areas of divergence from what may be previous local practice<br />
222 (particularly for GNU C) include:<br />
224 01. Pointers and references<br />
225 <code class="code"><br />
226 char* p = "flop";<br />
227 char& c = *p;<br />
229 char *p = "flop"; // wrong<br />
230 char &c = *p; // wrong<br />
233 Reason: In C++, definitions are mixed with executable code. Here,<br />
234 <code class="code">p</code> is being initialized, not <code class="code">*p</code>. This is near-universal<br />
235 practice among C++ programmers; it is normal for C hackers<br />
236 to switch spontaneously as they gain experience.<br />
238 02. Operator names and parentheses<br />
239 <code class="code"><br />
240 operator==(type)<br />
242 operator == (type) // wrong<br />
245 Reason: The <code class="code">==</code> is part of the function name. Separating<br />
246 it makes the declaration look like an expression.<br />
248 03. Function names and parentheses<br />
249 <code class="code"><br />
252 void mangle () // wrong<br />
255 Reason: no space before parentheses (except after a control-flow<br />
256 keyword) is near-universal practice for C++. It identifies the<br />
257 parentheses as the function-call operator or declarator, as<br />
258 opposed to an expression or other overloaded use of parentheses.<br />
260 04. Template function indentation<br />
261 <code class="code"><br />
262 template<typename T><br />
264 template_function(args)<br />
267 template<class T><br />
268 void template_function(args) {};<br />
271 Reason: In class definitions, without indentation whitespace is<br />
272 needed both above and below the declaration to distinguish<br />
273 it visually from other members. (Also, re: "typename"<br />
274 rather than "class".) <code class="code">T</code> often could be <code class="code">int</code>, which is<br />
275 not a class. ("class", here, is an anachronism.)<br />
277 05. Template class indentation<br />
278 <code class="code"><br />
279 template<typename _CharT, typename _Traits><br />
280 class basic_ios : public ios_base<br />
286 template<class _CharT, class _Traits><br />
287 class basic_ios : public ios_base<br />
293 template<class _CharT, class _Traits><br />
294 class basic_ios : public ios_base<br />
301 06. Enumerators<br />
302 <code class="code"><br />
305 space = _ISspace,<br />
306 print = _ISprint,<br />
307 cntrl = _IScntrl<br />
310 enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl };<br />
313 07. Member initialization lists<br />
314 All one line, separate from class name.<br />
316 <code class="code"><br />
317 gribble::gribble()<br />
318 : _M_private_data(0), _M_more_stuff(0), _M_helper(0)<br />
321 gribble::gribble() : _M_private_data(0), _M_more_stuff(0), _M_helper(0)<br />
325 08. Try/Catch blocks<br />
326 <code class="code"><br />
343 09. Member functions declarations and definitions<br />
344 Keywords such as extern, static, export, explicit, inline, etc<br />
345 go on the line above the function name. Thus<br />
347 <code class="code"><br />
351 virtual int foo()<br />
354 Reason: GNU coding conventions dictate return types for functions<br />
355 are on a separate line than the function name and parameter list<br />
356 for definitions. For C++, where we have member functions that can<br />
357 be either inline definitions or declarations, keeping to this<br />
358 standard allows all member function names for a given class to be<br />
359 aligned to the same margin, increasing readability.<br />
362 10. Invocation of member functions with "this->"<br />
363 For non-uglified names, use <code class="code">this->name</code> to call the function.<br />
365 <code class="code"><br />
366 this->sync()<br />
371 Reason: Koenig lookup.<br />
374 <code class="code"><br />
377 blah blah blah;<br />
378 } // namespace std<br />
382 namespace std {<br />
383 blah blah blah;<br />
384 } // namespace std<br />
387 12. Spacing under protected and private in class declarations:<br />
388 space above, none below<br />
391 <code class="code"><br />
401 13. Spacing WRT return statements.<br />
402 no extra spacing before returns, no parenthesis<br />
405 <code class="code"><br />
417 return (__ret);<br />
421 14. Location of global variables.<br />
422 All global variables of class type, whether in the "user visible"<br />
423 space (e.g., <code class="code">cin</code>) or the implementation namespace, must be defined<br />
424 as a character array with the appropriate alignment and then later<br />
425 re-initialized to the correct value.<br />
427 This is due to startup issues on certain platforms, such as AIX.<br />
428 For more explanation and examples, see <code class="filename">src/globals.cc</code>. All such<br />
429 variables should be contained in that file, for simplicity.<br />
431 15. Exception abstractions<br />
432 Use the exception abstractions found in <code class="filename">functexcept.h</code>, which allow<br />
433 C++ programmers to use this library with <code class="literal">-fno-exceptions</code>. (Even if<br />
434 that is rarely advisable, it's a necessary evil for backwards<br />
435 compatibility.)<br />
437 16. Exception error messages<br />
438 All start with the name of the function where the exception is<br />
439 thrown, and then (optional) descriptive text is added. Example:<br />
441 <code class="code"><br />
442 __throw_logic_error(__N("basic_string::_S_construct NULL not valid"));<br />
445 Reason: The verbose terminate handler prints out <code class="code">exception::what()</code>,<br />
446 as well as the typeinfo for the thrown exception. As this is the<br />
447 default terminate handler, by putting location info into the<br />
448 exception string, a very useful error message is printed out for<br />
449 uncaught exceptions. So useful, in fact, that non-programmers can<br />
450 give useful error messages, and programmers can intelligently<br />
451 speculate what went wrong without even using a debugger.<br />
453 17. The doxygen style guide to comments is a separate document,<br />
456 The library currently has a mixture of GNU-C and modern C++ coding<br />
457 styles. The GNU C usages will be combed out gradually.<br />
461 For nonstandard names appearing in Standard headers, we are constrained<br />
462 to use names that begin with underscores. This is called "uglification".<br />
463 The convention is:<br />
465 Local and argument names: <code class="literal">__[a-z].*</code><br />
467 Examples: <code class="code">__count __ix __s1</code><br />
469 Type names and template formal-argument names: <code class="literal">_[A-Z][^_].*</code><br />
471 Examples: <code class="code">_Helper _CharT _N</code><br />
473 Member data and function names: <code class="literal">_M_.*</code><br />
475 Examples: <code class="code">_M_num_elements _M_initialize ()</code><br />
477 Static data members, constants, and enumerations: <code class="literal">_S_.*</code><br />
479 Examples: <code class="code">_S_max_elements _S_default_value</code><br />
481 Don't use names in the same scope that differ only in the prefix,<br />
482 e.g. _S_top and _M_top. See BADNAMES for a list of forbidden names.<br />
483 (The most tempting of these seem to be and "_T" and "__sz".)<br />
485 Names must never have "__" internally; it would confuse name<br />
486 unmanglers on some targets. Also, never use "__[0-9]", same reason.<br />
488 --------------------------<br />
491 <code class="code"><br />
493 #ifndef _HEADER_<br />
494 #define _HEADER_ 1<br />
501 gribble() throw();<br />
503 gribble(const gribble&);<br />
506 gribble(int __howmany);<br />
509 operator=(const gribble&);<br />
512 ~gribble() throw ();<br />
514 // Start with a capital letter, end with a period.<br />
516 public_member(const char* __arg) const;<br />
518 // In-class function definitions should be restricted to one-liners.<br />
520 one_line() { return 0 }<br />
523 two_lines(const char* arg)<br />
524 { return strchr(arg, 'a'); }<br />
527 three_lines(); // inline, but defined below.<br />
529 // Note indentation.<br />
530 template<typename _Formal_argument><br />
532 public_template() const throw();<br />
534 template<typename _Iterator><br />
536 other_template();<br />
541 int _M_private_data;<br />
542 int _M_more_stuff;<br />
543 _Helper* _M_helper;<br />
544 int _M_private_function();<br />
553 _S_initialize_library();<br />
556 // More-or-less-standard language features described by lack, not presence.<br />
557 # ifndef _G_NO_LONGLONG<br />
558 extern long long _G_global_with_a_good_long_name; // avoid globals!<br />
561 // Avoid in-class inline definitions, define separately;<br />
562 // likewise for member class definitions:<br />
564 gribble::public_member() const<br />
565 { int __local = 0; return __local; }<br />
567 class gribble::_Helper<br />
571 friend class gribble;<br />
575 // Names beginning with "__": only for arguments and<br />
576 // local variables; never use "__" in a type name, or<br />
577 // within any name; never use "__[0-9]".<br />
579 #endif /* _HEADER_ */<br />
584 template<typename T> // notice: "typename", not "class", no space<br />
585 long_return_value_type<with_many, args><br />
586 function_name(char* pointer, // "char *pointer" is wrong.<br />
587 char* argument,<br />
588 const Reference& ref)<br />
590 // int a_local; /* wrong; see below. */<br />
596 int a_local = 0; // declare variable at first use.<br />
598 // char a, b, *p; /* wrong */<br />
600 char b = a + 1;<br />
601 char* c = "abc"; // each variable goes on its own line, always.<br />
603 // except maybe here...<br />
604 for (unsigned i = 0, mask = 1; mask; ++i, mask <<= 1) {<br />
609 gribble::gribble()<br />
610 : _M_private_data(0), _M_more_stuff(0), _M_helper(0)<br />
614 gribble::three_lines()<br />
616 // doesn't fit in one line.<br />
618 } // namespace std<br />
620 </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="source_organization.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="source_design_notes.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="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Design Notes</td></tr></table></div></body></html>