===================================================================
@@ -52,7 +52,7 @@
organization is ANSI and their web-site is right
<ulink url="http://www.ansi.org">here.</ulink>
(And if you've already registered with them, clicking this link will take you to directly to the place where you can
- <ulink url="http://webstore.ansi.org/RecordDetail.aspx?sku=ISO%2FIEC+14882:2003">buy the standard on-line.)</ulink>
+ <ulink url="http://webstore.ansi.org/RecordDetail.aspx?sku=ISO%2FIEC+14882:2003">buy the standard on-line</ulink>.)
</para>
</listitem>
@@ -509,7 +509,7 @@ indicate a place that may require attent
__embedded_cplusplus
// long double conversion members mangled as __opr
// http://gcc.gnu.org/ml/libstdc++/1999-q4/msg00060.html
- _opr
+ __opr
</literallayout>
</sect2>
@@ -520,52 +520,60 @@ indicate a place that may require attent
it is intended to precede the recommendations of the GNU Coding
Standard, which can be referenced in full here:
- http://www.gnu.org/prep/standards/standards.html#Formatting
+ <ulink url="http://www.gnu.org/prep/standards/standards.html#Formatting">http://www.gnu.org/prep/standards/standards.html#Formatting</ulink>
The rest of this is also interesting reading, but skip the "Design
Advice" part.
The GCC coding conventions are here, and are also useful:
- http://gcc.gnu.org/codingconventions.html
+ <ulink url="http://gcc.gnu.org/codingconventions.html">http://gcc.gnu.org/codingconventions.html</ulink>
In addition, because it doesn't seem to be stated explicitly anywhere
else, there is an 80 column source limit.
- ChangeLog entries for member functions should use the
+ <filename>ChangeLog</filename> entries for member functions should use the
classname::member function name syntax as follows:
- 1999-04-15 Dennis Ritchie <dr@att.com>
+<code>
+1999-04-15 Dennis Ritchie <dr@att.com>
* src/basic_file.cc (__basic_file::open): Fix thinko in
_G_HAVE_IO_FILE_OPEN bits.
+</code>
Notable areas of divergence from what may be previous local practice
(particularly for GNU C) include:
01. Pointers and references
- char* p = "flop";
- char& c = *p;
- -NOT-
- char *p = "flop"; // wrong
- char &c = *p; // wrong
+ <code>
+ char* p = "flop";
+ char& c = *p;
+ -NOT-
+ char *p = "flop"; // wrong
+ char &c = *p; // wrong
+ </code>
Reason: In C++, definitions are mixed with executable code. Here,
- p is being initialized, not *p. This is near-universal
+ <code>p</code> is being initialized, not <code>*p</code>. This is near-universal
practice among C++ programmers; it is normal for C hackers
to switch spontaneously as they gain experience.
02. Operator names and parentheses
- operator==(type)
- -NOT-
- operator == (type) // wrong
+ <code>
+ operator==(type)
+ -NOT-
+ operator == (type) // wrong
+ </code>
- Reason: The == is part of the function name. Separating
+ Reason: The <code>==</code> is part of the function name. Separating
it makes the declaration look like an expression.
03. Function names and parentheses
- void mangle()
- -NOT-
- void mangle () // wrong
+ <code>
+ void mangle()
+ -NOT-
+ void mangle () // wrong
+ </code>
Reason: no space before parentheses (except after a control-flow
keyword) is near-universal practice for C++. It identifies the
@@ -573,86 +581,98 @@ indicate a place that may require attent
opposed to an expression or other overloaded use of parentheses.
04. Template function indentation
- template<typename T>
- void
- template_function(args)
- { }
- -NOT-
- template<class T>
- void template_function(args) {};
+ <code>
+ template<typename T>
+ void
+ template_function(args)
+ { }
+ -NOT-
+ template<class T>
+ void template_function(args) {};
+ </code>
Reason: In class definitions, without indentation whitespace is
needed both above and below the declaration to distinguish
it visually from other members. (Also, re: "typename"
- rather than "class".) T often could be int, which is
+ rather than "class".) <code>T</code> often could be <code>int</code>, which is
not a class. ("class", here, is an anachronism.)
05. Template class indentation
- template<typename _CharT, typename _Traits>
- class basic_ios : public ios_base
- {
- public:
- // Types:
- };
- -NOT-
- template<class _CharT, class _Traits>
- class basic_ios : public ios_base
- {
- public:
- // Types:
- };
- -NOT-
- template<class _CharT, class _Traits>
- class basic_ios : public ios_base
- {
- public:
- // Types:
- };
+ <code>
+ template<typename _CharT, typename _Traits>
+ class basic_ios : public ios_base
+ {
+ public:
+ // Types:
+ };
+ -NOT-
+ template<class _CharT, class _Traits>
+ class basic_ios : public ios_base
+ {
+ public:
+ // Types:
+ };
+ -NOT-
+ template<class _CharT, class _Traits>
+ class basic_ios : public ios_base
+ {
+ public:
+ // Types:
+ };
+ </code>
06. Enumerators
- enum
- {
- space = _ISspace,
- print = _ISprint,
- cntrl = _IScntrl
- };
- -NOT-
- enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl };
+ <code>
+ enum
+ {
+ space = _ISspace,
+ print = _ISprint,
+ cntrl = _IScntrl
+ };
+ -NOT-
+ enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl };
+ </code>
07. Member initialization lists
All one line, separate from class name.
- gribble::gribble()
- : _M_private_data(0), _M_more_stuff(0), _M_helper(0);
- { }
- -NOT-
- gribble::gribble() : _M_private_data(0), _M_more_stuff(0), _M_helper(0);
- { }
+ <code>
+ gribble::gribble()
+ : _M_private_data(0), _M_more_stuff(0), _M_helper(0)
+ { }
+ -NOT-
+ gribble::gribble() : _M_private_data(0), _M_more_stuff(0), _M_helper(0)
+ { }
+ </code>
08. Try/Catch blocks
- try
- {
- //
- }
- catch (...)
- {
- //
- }
- -NOT-
- try {
- //
- } catch(...) {
- //
- }
+ <code>
+ try
+ {
+ //
+ }
+ catch (...)
+ {
+ //
+ }
+ -NOT-
+ try {
+ //
+ } catch(...) {
+ //
+ }
+ </code>
09. Member functions declarations and definitions
Keywords such as extern, static, export, explicit, inline, etc
go on the line above the function name. Thus
+ <code>
virtual int
foo()
-NOT-
virtual int foo()
+ </code>
Reason: GNU coding conventions dictate return types for functions
are on a separate line than the function name and parameter list
@@ -663,42 +683,49 @@ indicate a place that may require attent
10. Invocation of member functions with "this->"
- For non-uglified names, use this->name to call the function.
+ For non-uglified names, use <code>this->name</code> to call the function.
+ <code>
this->sync()
-NOT-
sync()
+ </code>
Reason: Koenig lookup.
11. Namespaces
+ <code>
namespace std
{
- blah blah blah;
+ blah blah blah;
} // namespace std
-NOT-
namespace std {
- blah blah blah;
+ blah blah blah;
} // namespace std
+ </code>
12. Spacing under protected and private in class declarations:
space above, none below
i.e.
+ <code>
public:
- int foo;
+ int foo;
-NOT-
public:
- int foo;
+ int foo;
+ </code>
13. Spacing WRT return statements.
no extra spacing before returns, no parenthesis
i.e.
+ <code>
}
return __ret;
@@ -711,21 +738,22 @@ indicate a place that may require attent
}
return (__ret);
+ </code>
14. Location of global variables.
All global variables of class type, whether in the "user visible"
- space (e.g., cin) or the implementation namespace, must be defined
+ space (e.g., <code>cin</code>) or the implementation namespace, must be defined
as a character array with the appropriate alignment and then later
re-initialized to the correct value.
This is due to startup issues on certain platforms, such as AIX.
- For more explanation and examples, see src/globals.cc. All such
+ For more explanation and examples, see <filename>src/globals.cc</filename>. All such
variables should be contained in that file, for simplicity.
15. Exception abstractions
- Use the exception abstractions found in functexcept.h, which allow
- C++ programmers to use this library with -fno-exceptions. (Even if
+ Use the exception abstractions found in <filename class="headerfile">functexcept.h</filename>, which allow
+ C++ programmers to use this library with <literal>-fno-exceptions</literal>. (Even if
that is rarely advisable, it's a necessary evil for backwards
compatibility.)
@@ -733,9 +761,11 @@ indicate a place that may require attent
All start with the name of the function where the exception is
thrown, and then (optional) descriptive text is added. Example:
+ <code>
__throw_logic_error(__N("basic_string::_S_construct NULL not valid"));
+ </code>
- Reason: The verbose terminate handler prints out exception::what(),
+ Reason: The verbose terminate handler prints out <code>exception::what()</code>,
as well as the typeinfo for the thrown exception. As this is the
default terminate handler, by putting location info into the
exception string, a very useful error message is printed out for
@@ -755,21 +785,21 @@ indicate a place that may require attent
to use names that begin with underscores. This is called "uglification".
The convention is:
- Local and argument names: __[a-z].*
+ Local and argument names: <literal>__[a-z].*</literal>
- Examples: __count __ix __s1
+ Examples: <code>__count __ix __s1</code>
- Type names and template formal-argument names: _[A-Z][^_].*
+ Type names and template formal-argument names: <literal>_[A-Z][^_].*</literal>
- Examples: _Helper _CharT _N
+ Examples: <code>_Helper _CharT _N</code>
- Member data and function names: _M_.*
+ Member data and function names: <literal>_M_.*</literal>
- Examples: _M_num_elements _M_initialize ()
+ Examples: <code>_M_num_elements _M_initialize ()</code>
- Static data members, constants, and enumerations: _S_.*
+ Static data members, constants, and enumerations: <literal>_S_.*</literal>
- Examples: _S_max_elements _S_default_value
+ Examples: <code>_S_max_elements _S_default_value</code>
Don't use names in the same scope that differ only in the prefix,
e.g. _S_top and _M_top. See BADNAMES for a list of forbidden names.
@@ -781,87 +811,88 @@ indicate a place that may require attent
--------------------------
[BY EXAMPLE]
+ <code>
#ifndef _HEADER_
#define _HEADER_ 1
namespace std
{
- class gribble
- {
- public:
- gribble() throw();
+ class gribble
+ {
+ public:
+ gribble() throw();
- gribble(const gribble&);
+ gribble(const gribble&);
- explicit
- gribble(int __howmany);
+ explicit
+ gribble(int __howmany);
- gribble&
- operator=(const gribble&);
+ gribble&
+ operator=(const gribble&);
- virtual
- ~gribble() throw ();
+ virtual
+ ~gribble() throw ();
- // Start with a capital letter, end with a period.
- inline void
- public_member(const char* __arg) const;
+ // Start with a capital letter, end with a period.
+ inline void
+ public_member(const char* __arg) const;
- // In-class function definitions should be restricted to one-liners.
- int
- one_line() { return 0 }
+ // In-class function definitions should be restricted to one-liners.
+ int
+ one_line() { return 0 }
- int
- two_lines(const char* arg)
- { return strchr(arg, 'a'); }
+ int
+ two_lines(const char* arg)
+ { return strchr(arg, 'a'); }
- inline int
- three_lines(); // inline, but defined below.
+ inline int
+ three_lines(); // inline, but defined below.
- // Note indentation.
- template<typename _Formal_argument>
- void
- public_template() const throw();
+ // Note indentation.
+ template<typename _Formal_argument>
+ void
+ public_template() const throw();
- template<typename _Iterator>
- void
- other_template();
+ template<typename _Iterator>
+ void
+ other_template();
- private:
- class _Helper;
+ private:
+ class _Helper;
- int _M_private_data;
- int _M_more_stuff;
- _Helper* _M_helper;
- int _M_private_function();
+ int _M_private_data;
+ int _M_more_stuff;
+ _Helper* _M_helper;
+ int _M_private_function();
- enum _Enum
- {
- _S_one,
- _S_two
- };
-
- static void
- _S_initialize_library();
- };
+ enum _Enum
+ {
+ _S_one,
+ _S_two
+ };
- // More-or-less-standard language features described by lack, not presence.
+ static void
+ _S_initialize_library();
+ };
+
+ // More-or-less-standard language features described by lack, not presence.
# ifndef _G_NO_LONGLONG
- extern long long _G_global_with_a_good_long_name; // avoid globals!
+ extern long long _G_global_with_a_good_long_name; // avoid globals!
# endif
- // Avoid in-class inline definitions, define separately;
- // likewise for member class definitions:
- inline int
- gribble::public_member() const
- { int __local = 0; return __local; }
-
- class gribble::_Helper
- {
- int _M_stuff;
+ // Avoid in-class inline definitions, define separately;
+ // likewise for member class definitions:
+ inline int
+ gribble::public_member() const
+ { int __local = 0; return __local; }
+
+ class gribble::_Helper
+ {
+ int _M_stuff;
- friend class gribble;
- };
+ friend class gribble;
+ };
}
// Names beginning with "__": only for arguments and
@@ -873,41 +904,42 @@ indicate a place that may require attent
namespace std
{
- template<typename T> // notice: "typename", not "class", no space
- long_return_value_type<with_many, args>
- function_name(char* pointer, // "char *pointer" is wrong.
- char* argument,
- const Reference& ref)
- {
- // int a_local; /* wrong; see below. */
- if (test)
- {
- nested code
- }
-
- int a_local = 0; // declare variable at first use.
-
- // char a, b, *p; /* wrong */
- char a = 'a';
- char b = a + 1;
- char* c = "abc"; // each variable goes on its own line, always.
-
- // except maybe here...
- for (unsigned i = 0, mask = 1; mask; ++i, mask <<= 1) {
- // ...
- }
- }
-
- gribble::gribble()
- : _M_private_data(0), _M_more_stuff(0), _M_helper(0);
- { }
-
- inline int
- gribble::three_lines()
- {
- // doesn't fit in one line.
- }
+ template<typename T> // notice: "typename", not "class", no space
+ long_return_value_type<with_many, args>
+ function_name(char* pointer, // "char *pointer" is wrong.
+ char* argument,
+ const Reference& ref)
+ {
+ // int a_local; /* wrong; see below. */
+ if (test)
+ {
+ nested code
+ }
+
+ int a_local = 0; // declare variable at first use.
+
+ // char a, b, *p; /* wrong */
+ char a = 'a';
+ char b = a + 1;
+ char* c = "abc"; // each variable goes on its own line, always.
+
+ // except maybe here...
+ for (unsigned i = 0, mask = 1; mask; ++i, mask <<= 1) {
+ // ...
+ }
+ }
+
+ gribble::gribble()
+ : _M_private_data(0), _M_more_stuff(0), _M_helper(0)
+ { }
+
+ int
+ gribble::three_lines()
+ {
+ // doesn't fit in one line.
+ }
} // namespace std
+ </code>
</literallayout>
</sect2>
</sect1>