2 C++ Standard Library Style Guidelines DRAFT 2001-01-15
3 -------------------------------------
5 This library is written to appropriate C++ coding standards. As such,
6 it is intended to precede the recommendations of the GNU Coding
7 Standard, which can be referenced here:
9 http://www.gnu.org/prep/standards_toc.html
11 ChangeLog entries for member functions should use the
12 classname::member function name syntax as follows:
14 1999-04-15 Dennis Ritchie <dr@att.com>
16 * src/basic_file.cc (__basic_file::open): Fix thinko in
17 _G_HAVE_IO_FILE_OPEN bits.
19 Notable areas of divergence from what may be previous local practice
20 (particularly for GNU C) include:
22 01. Pointers and references
26 char *p = "flop"; // wrong
27 char &c = *p; // wrong
29 Reason: In C++, definitions are mixed with executable code. Here,
30 p is being initialized, not *p. This is near-universal
31 practice among C++ programmers; it is normal for C hackers
32 to switch spontaneously as they gain experience.
34 02. Operator names and parentheses
37 operator == (type) // wrong
39 Reason: The == is part of the function name. Separating
40 it makes the declaration look like an expression.
42 03. Function names and parentheses
45 void mangle () // wrong
47 Reason: no space before parentheses (except after a control-flow
48 keyword) is near-universal practice for C++. It identifies the
49 parentheses as the function-call operator or declarator, as
50 opposed to an expression or other overloaded use of parentheses.
52 04. Template function indentation
55 template_function(args)
59 void template_function(args) {};
61 Reason: In class definitions, without indentation whitespace is
62 needed both above and below the declaration to distinguish
63 it visually from other members. (Also, re: "typename"
64 rather than "class".) T often could be int, which is
65 not a class. ("class", here, is an anachronism.)
67 05. Template class indentation
68 template<typename _CharT, typename _Traits>
69 class basic_ios : public ios_base
75 template<class _CharT, class _Traits>
76 class basic_ios : public ios_base
82 template<class _CharT, class _Traits>
83 class basic_ios : public ios_base
97 enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl };
99 07. Member initialization lists
100 All one line, separate from class name.
103 : _M_private_data(0), _M_more_stuff(0), _M_helper(0);
106 gribble::gribble() : _M_private_data(0), _M_more_stuff(0), _M_helper(0);
125 09. Member functions declarations and definitions
126 Keywords such as extern, static, export, explicit, inline, etc
127 go on the line above the function name. Thus
134 Reason: GNU coding conventions dictate return types for functions
135 are on a separate line than the function name and parameter list
136 for definitions. For C++, where we have member functions that can
137 be either inline definitions or declarations, keeping to this
138 standard allows all member function names for a given class to be
139 aligned to the same margin, increasing readibility.
142 10. Invocation of member functions with "this->"
143 For non-uglified names, use this->name to call the function.
149 Reason: Koenig lookup.
163 12. Spacing under protected and private in class declarations:
164 space above, none below
175 13. Spacing WRT return statements.
176 no extra spacing before returns, no parenthesis
193 14. Location of global variables.
194 All global variables of class type, whether in the "user visable"
195 space (e.g., cin) or the implementation namespace, must be defined
196 as a character array with the appropriate alignment and then later
197 re-initialized to the correct value.
199 This is due to startup issues on certain platforms, such as AIX.
200 For more explanation and examples, see src/globals.cc. All such
201 variables should be contained in that file, for simplicity.
203 15. Exception abstractions
204 Use the exception abstractions found in functexcept.h, which allow
205 C++ programmers to use this library with -fno-exceptions. (Even if
206 that is rarely advisable, it's a necessary evil for backwards
209 16. Exception error messages
210 All start with the name of the function where the exception is
211 thrown, and then (optional) descriptive text is added. Example:
213 __throw_logic_error(__N("basic_string::_S_construct NULL not valid"));
215 Reason: The verbose terminate handler prints out exception::what(),
216 as well as the typeinfo for the thrown exception. As this is the
217 default terminate handler, by putting location info into the
218 exception string, a very useful error message is printed out for
219 uncaught exceptions. So useful, in fact, that non-programmers can
220 give useful error messages, and programmers can intelligently
221 speculate what went wrong without even using a debugger.
223 The library currently has a mixture of GNU-C and modern C++ coding
224 styles. The GNU C usages will be combed out gradually.
228 For nonstandard names appearing in Standard headers, we are constrained
229 to use names that begin with underscores. This is called "uglification".
232 Local and argument names: __[a-z].*
234 Examples: __count __ix __s1
236 Type names and template formal-argument names: _[A-Z][^_].*
238 Examples: _Helper _CharT _N
240 Member data and function names: _M_.*
242 Examples: _M_num_elements _M_initialize ()
244 Static data members, constants, and enumerations: _S_.*
246 Examples: _S_max_elements _S_default_value
248 Don't use names in the same scope that differ only in the prefix,
249 e.g. _S_top and _M_top. See BADNAMES for a list of forbidden names.
250 (The most tempting of these seem to be and "_T" and "__sz".)
252 Names must never have "__" internally; it would confuse name
253 unmanglers on some targets. Also, never use "__[0-9]", same reason.
255 --------------------------
270 gribble(const gribble&);
273 gribble(int __howmany);
276 operator=(const gribble&);
283 public_member(const char* __arg) const;
285 // in-class function definitions should be restricted to one-liners.
287 one_line() { return 0 }
290 two_lines(const char* arg)
291 { return strchr(arg, 'a'); }
294 three_lines(); // inline, but defined below.
297 template<typename _Formal_argument>
299 public_template() const throw();
301 template<typename _Iterator>
311 int _M_private_function();
320 _S_initialize_library();
323 // More-or-less-standard language features described by lack, not presence:
324 # ifndef _G_NO_LONGLONG
325 extern long long _G_global_with_a_good_long_name; // avoid globals!
328 // Avoid in-class inline definitions, define separately;
329 // likewise for member class definitions:
331 gribble::public_member() const
332 { int __local = 0; return __local; }
334 class gribble::_Helper
338 friend class gribble;
342 // Names beginning with "__": only for arguments and
343 // local variables; never use "__" in a type name, or
344 // within any name; never use "__[0-9]".
346 #endif /* _HEADER_ */
351 template<typename T> // notice: "typename", not "class", no space
352 long_return_value_type<with_many, args>
353 function_name(char* pointer, // "char *pointer" is wrong.
355 const Reference& ref)
357 // int a_local; /* wrong; see below. */
363 int a_local = 0; // declare variable at first use.
365 // char a, b, *p; /* wrong */
368 char* c = "abc"; // each variable goes on its own line, always.
370 // except maybe here...
371 for (unsigned i = 0, mask = 1; mask; ++i, mask <<= 1) {
377 : _M_private_data(0), _M_more_stuff(0), _M_helper(0);
381 gribble::three_lines()
383 // doesn't fit in one line.