<?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.73.2" /><meta name="keywords" content=" ISO C++ , library " /><link rel="start" 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 />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>