Patchwork [wwwdocs] Update coding conventions for C++

login
register
mail settings
Submitter Lawrence Crowl
Date June 18, 2012, 10:28 p.m.
Message ID <CAGqM8fbU2d7v_aG--LqGhmzi1dOGcHq030BdaSndR6yvT4Ud3A@mail.gmail.com>
Download mbox | patch
Permalink /patch/165620/
State New
Headers show

Comments

Lawrence Crowl - June 18, 2012, 10:28 p.m.
This patch updates the coding conventions to C++.  The primary
source file is codingconventions.html.  The coding conventions now
refer to a new file, codingrationale.html, providing the rationale
for some of the C++ conventions.  The two files in question are
attached whole for your convenience.

The "Portability" section has some changes.  The "Miscellaneous
Conventions" section moves later and become part of the "C and C++
Language Conventions" section.  The bulk of the change consists of
additions to the "C and C++ Language Conventions" section and the
addition of an entirely new "C++ Language Conventions" section.
I added a table of contents.

I have removed lines from the around the html tag, as they are
causing my mail to be rejected.  If you get this message twice, you
now know why.  :-)

Please review.


+</p>
+
+</body>
+</html>
Diego Novillo - June 25, 2012, 4:29 p.m.
[ Added doc maintainers in CC ]

While I'm not particularly interested in the details of the coding
conventions, I am interested in getting them in getting them installed
before we merge cxx-conversion to trunk.

Joseph, Gerald, do we have a process for accepting changes to coding
conventions?

It has been a week since the conventions were posted and I have seen
no comments on the patch.


Thanks.  Diego.

On Mon, Jun 18, 2012 at 6:28 PM, Lawrence Crowl <crowl@google.com> wrote:
> This patch updates the coding conventions to C++.  The primary
> source file is codingconventions.html.  The coding conventions now
> refer to a new file, codingrationale.html, providing the rationale
> for some of the C++ conventions.  The two files in question are
> attached whole for your convenience.
>
> The "Portability" section has some changes.  The "Miscellaneous
> Conventions" section moves later and become part of the "C and C++
> Language Conventions" section.  The bulk of the change consists of
> additions to the "C and C++ Language Conventions" section and the
> addition of an entirely new "C++ Language Conventions" section.
> I added a table of contents.
>
> I have removed lines from the around the html tag, as they are
> causing my mail to be rejected.  If you get this message twice, you
> now know why.  :-)
>
> Please review.
>
>
> Index: codingconventions.html
> ===================================================================
> RCS file: /cvs/gcc/wwwdocs/htdocs/codingconventions.html,v
> retrieving revision 1.66
> diff -u -u -r1.66 codingconventions.html
> --- codingconventions.html      19 Feb 2012 00:45:34 -0000      1.66
> +++ codingconventions.html      18 Jun 2012 22:04:49 -0000
> @@ -1,4 +1,8 @@
>
>  <head>
>  <title>GCC Coding Conventions</title>
> @@ -15,8 +19,56 @@
>  code to follow these conventions, it is best to send changes to follow
>  the conventions separately from any other changes to the code.</p>
>
> +<p>
> +<a href="#Documentation">Documentation</a><br />
> +<a href="#ChangeLogs">ChangeLogs</a><br />
> +<a href="#Portability">Portability</a><br />
> +<a href="#Makefiles">Makefiles</a><br />
> +<a href="#Testsuite">Testsuite Conventions</a><br />
> +<a href="#Diagnostics">Diagnostics Conventions</a><br />
> +<a href="#Spelling">Spelling, terminology and markup</a><br />
> +<a href="#CandCxx">C and C++ Language Conventions</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#C_Options">Compiler Options</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#C_Language">Language Use</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Assertions">Assertions</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Character">Character Testing</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Error">Error Node Testing</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Generated">Parameters Affecting Generated Code</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#C_Inlining">Inlining Functions</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#C_Formatting">Formatting
> Conventions</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Line">Line
> Length</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#C_Names">Names</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Expressions">Expressions</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Calls">Function Calls</a><br />
> +<a href="#Cxx_Conventions">C++ Language Conventions</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Cxx_Language">Language Use</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Variable">Variable Definitions</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Struct_Use">Struct Definitions</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Class_Use">Class Definitions</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Constructors">Constructors and Destructors</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Conversions">Conversions</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Over_Func">Overloading Functions</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Over_Oper">Overloading Operators</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Default">Default Arguments</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Cxx_Inlining">Inlining Functions</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Template_Use">Templates</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Namespace_Use">Namespaces</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#RTTI">RTTI
> and <code>dynamic_cast</code></a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Casts">Other Casts</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Exceptions">Exceptions</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Standard_Library">The Standard Library</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Cxx_Formatting">Formatting
> Conventions</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Cxx_Names">Names</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Struct_Form">Struct Definitions</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Class_Form">Class Definitions</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Member_Form">Class Member Definitions</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Template_Form">Templates</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#ExternC">Extern "C"</a><br />
> +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
> href="#Namespace_Form">Namespaces</a><br />
> +</p>
>
> -<h2>Documentation</h2>
> +
> +<h2><a name="Documentation">Documentation</a></h2>
>
>  <p>Documentation, both of user interfaces and of internals, must be
>  maintained and kept up to date.  In particular:</p>
> @@ -43,7 +95,7 @@
>  </ul>
>
>
> -<h2>ChangeLogs</h2>
> +<h2><a name="ChangeLogs">ChangeLogs</a></h2>
>
>  <p>GCC requires ChangeLog entries for documentation changes; for the web
>  pages (apart from <code>java/</code> and <code>libstdc++/</code>) the CVS
> @@ -71,20 +123,61 @@
>  <code>java/58</code> is the actual number of the PR) at the top
>  of the ChangeLog entry.</p>
>
> -<h2>Portability</h2>
> +<h2><a name="Portability">Portability</a></h2>
>
>  <p>There are strict requirements for portability of code in GCC to
> -older systems whose compilers do not implement all of the ISO C standard.
> -GCC requires at least an ANSI C89 or ISO C90 host compiler, and code
> -should avoid pre-standard style function definitions, unnecessary
> -function prototypes and use of the now deprecated @code{PARAMS} macro.
> +older systems whose compilers do not implement all of the
> +latest ISO C and C++ standards.
> +</p>
> +
> +<p>
> +The directories
> +<code>gcc</code>, <code>libcpp</code> and <code>fixincludes</code>
> +may use C++03.
> +They may also use the <code>long long</code> type
> +if the host C++ compiler supports it.
> +Furthermore,
> +these directories <em>should</em> also be compatible with C++11.
> +</p>
> +
> +<p>
> +The directories libiberty and libdecnumber must use C
> +and require at least an ANSI C89 or ISO C90 host compiler.
> +C code should avoid pre-standard style function definitions, unnecessary
> +function prototypes and use of the now deprecated <code>PARAMS</code>
> macro.
>  See <a
> href="http://gcc.gnu.org/cgi-bin/cvsweb.cgi/~checkout~/gcc/gcc/README.Portability?content-type=text/plain&amp;only_with_tag=HEAD">README.Portability</a>
>  for details of some of the portability problems that may arise.  Some
>  of these problems are warned about by <code>gcc -Wtraditional</code>,
>  which is included in the default warning options in a bootstrap.
> -(Code outside the C front end is only compiled by GCC, so such
> -requirements do not apply to it.)</p>
> +</p>
> +
> +<p>
> +Every version of GCC must be buildable by the previous version of GCC.
> +This rule helps ensure smooth development of the next version.
> +However, it doesn't help so much when you do not have a previous version.
> +So, the more important rule is that every version must bootstrap,
> +which means that version can develop itself.
> +Note that this statement does not preclude
> +a need to build GCC with other compilers.
> +</p>
> +
> +<p>
> +We will periodically pick a stable version of GCC,
> +and require that that version of GCC be able to build
> +all versions of GCC up to and including the next stable version.
> +E.g., we may decide that all newer versions of GCC
> +should be buildable with GCC 4.3.5.
> +</p>
> +
> +<p>
> +It is desirable that it be possible to build GCC
> +with C++ compilers other than GCC itself.
> +If testing reveals that reasonably recent versions of non-GCC C++
> compilers
> +cannot compile GCC,
> +then GCC code should be adjusted accordingly.
> +(Avoiding unusual language constructs helps immensely.)
> +</p>
>
>  <p>The programs included in GCC are linked with the
>  libiberty library, which will replace some standard
> @@ -108,12 +201,6 @@
>  the release cycle, to reduce the risk involved in fixing a problem
>  that only shows up on one particular system.</p>
>
> -<p>Avoid the use of identifiers or idioms that would prevent code
> -compiling with a C++ compiler.  Identifiers such as <code>new</code>
> -or <code>class</code>, that are reserved words in C++, should not be
> -used as variables or field names.  Explicit casts should be used to
> -convert between <code>void*</code> and other pointer types.</p>
> -
>  <p>Function prototypes for extern functions should only occur in
>  header files.  Functions should be ordered within source files to
>  minimize the number of function prototypes, by defining them before
> @@ -121,13 +208,13 @@
>  necessary, to break mutually recursive cycles.</p>
>
>
> -<h2>Makefiles</h2>
> +<h2><a name="Makefiles">Makefiles</a></h2>
>
>  <p><code>touch</code> should never be used in GCC Makefiles.  Instead
>  of <code>touch foo</code> always use <code>$(STAMP) foo</code>.</p>
>
>
> -<h2>Testsuite Conventions</h2>
> +<h2><a name="Testsuite">Testsuite Conventions</a></h2>
>
>  <p>Every language or library feature, whether standard or a GNU
>  extension, and every warning GCC can give, should have testcases
> @@ -157,7 +244,7 @@
>  to the test suite.</p>
>
>
> -<h2>Diagnostics Conventions</h2>
> +<h2><a name="Diagnostics">Diagnostics Conventions</a></h2>
>  <ul>
>
>  <li>Use of the <code>input_location</code> global, and of the
> @@ -208,66 +295,7 @@
>  </ul>
>
>
> -<h2>Miscellaneous Conventions</h2>
> -
> -<p>Code should use <code>gcc_assert(EXPR)</code> to check invariants.
> -Use <code>gcc_unreachable()</code> to mark places that should never be
> -reachable (such as an unreachable <code>default</code> case of a
> -switch).  Do not use <code>gcc_assert(0)</code> for such purposes, as
> -<code>gcc_unreachable</code> gives the compiler more information.  The
> -assertions are enabled unless explicitly configured off with
> -<code>--enable-checking=none</code>.  Do not use <code>abort</code>.
> -User input should never be validated by either <code>gcc_assert</code>
> -or <code>gcc_unreachable</code>.  If the checks are expensive or the
> -compiler can reasonably carry on after the error, they may be
> -conditioned on <code>--enable-checking</code>.</p>
> -
> -<p>Code testing properties of characters from user source code should
> -use macros such as <code>ISALPHA</code> from <code>safe-ctype.h</code>
> -instead of the standard functions such as <code>isalpha</code> from
> -<code>&lt;ctype.h&gt;</code> to avoid any locale-dependency of the
> -language accepted.</p>
> -
> -<p>Code in GCC should use the following formatting conventions:</p>
> -
> -<table cellpadding="4">
> -<tr>
> -  <th align="right">Use...</th><th align="left">...instead of</th>
> -</tr><tr>
> -  <td align="right"><code>!x</code></td><td><code>! x</code></td>
> -</tr><tr>
> -  <td align="right"><code>~x</code></td><td><code>~ x</code></td>
> -</tr><tr>
> -  <td align="right"><code>-x</code> (unary minus)</td><td><code>-
> x</code></td>
> -</tr><tr>
> -  <td align="right"><code>(foo) x</code> (cast)</td>
> -  <td><code>(foo)x</code></td>
> -</tr><tr>
> -  <td align="right"><code>*x</code> (pointer dereference)</td>
> -  <td><code>* x</code></td>
> -</tr>
> -</table>
> -
> -
> -<p>Macros names should be in <code>ALL_CAPS</code> when it's important
> -to be aware that it's a macro (e.g. accessors and simple predicates),
> -but in lowercase (e.g., <code>size_int</code>) where the macro is a
> -wrapper for efficiency that should be considered as a function; see
> -messages <a
> -href="http://gcc.gnu.org/ml/gcc-patches/2000-09/msg00901.html">1</a>
> -and <a
> -href="http://gcc.gnu.org/ml/gcc-patches/2000-09/msg00912.html">2</a>.</p>
> -
> -<p>Testing for <code>ERROR_MARK</code>s should be done by comparing
> -against <code>error_mark_node</code> rather than by comparing the
> -<code>TREE_CODE</code> against <code>ERROR_MARK</code>; see <a
> -href="http://gcc.gnu.org/ml/gcc-patches/2000-10/msg00792.html">message</a>.</p>
> -
> -<p>Internal numeric parameters that may affect generated code should
> -be controlled by <code>--param</code> rather than being hardcoded.</p>
> -
> -
> -<h2>Spelling, terminology and markup</h2>
> +<h2><a name="Spelling">Spelling, terminology and markup</a></h2>
>
>  <p>The following conventions of spelling and terminology apply
>  throughout GCC, including the manuals, web pages, diagnostics,
> @@ -645,5 +673,682 @@
>
>  </ul>
>
> +
> +<h2><a name="CandCxx">C and C++ Language Conventions</a></h2>
> +
> +<p>
> +The following conventions apply to both C and C++.
> +</p>
> +
> +
> +<h3><a name="C_Options">Compiler Options</a></h3>
> +
> +<p>
> +The compiler must build cleanly with <code>-Wall -Wextra</code>.
> +</p>
> +
> +
> +<h3><a name="C_Language">Language Use</a></h3>
> +
> +
> +<h4><a name="Assertions">Assertions</a></h4>
> +
> +<p>Code should use <code>gcc_assert(EXPR)</code> to check invariants.
> +Use <code>gcc_unreachable()</code> to mark places that should never be
> +reachable (such as an unreachable <code>default</code> case of a
> +switch).  Do not use <code>gcc_assert(0)</code> for such purposes, as
> +<code>gcc_unreachable</code> gives the compiler more information.  The
> +assertions are enabled unless explicitly configured off with
> +<code>--enable-checking=none</code>.  Do not use <code>abort</code>.
> +User input should never be validated by either <code>gcc_assert</code>
> +or <code>gcc_unreachable</code>.  If the checks are expensive or the
> +compiler can reasonably carry on after the error, they may be
> +conditioned on <code>--enable-checking</code>.</p>
> +
> +
> +<h4><a name="Character">Character Testing</a></h4>
> +
> +<p>Code testing properties of characters from user source code should
> +use macros such as <code>ISALPHA</code> from <code>safe-ctype.h</code>
> +instead of the standard functions such as <code>isalpha</code> from
> +<code>&lt;ctype.h&gt;</code> to avoid any locale-dependency of the
> +language accepted.</p>
> +
> +
> +<h4><a name="Error">Error Node Testing</a></h4>
> +
> +<p>Testing for <code>ERROR_MARK</code>s should be done by comparing
> +against <code>error_mark_node</code> rather than by comparing the
> +<code>TREE_CODE</code> against <code>ERROR_MARK</code>; see <a
> +href="http://gcc.gnu.org/ml/gcc-patches/2000-10/msg00792.html">message</a>.</p>
> +
> +
> +<h4><a name="Generated">Parameters Affecting Generated Code</a></h4>
> +
> +<p>Internal numeric parameters that may affect generated code should
> +be controlled by <code>--param</code> rather than being hardcoded.</p>
> +
> +
> +<h4><a name="C_Inlining">Inlining Functions</a></h4>
> +
> +<p>
> +Inlining functions only when
> +you have reason to believe that
> +the expansion of the function is smaller than a call to the function
> +or that inlining is significant to the run-time of the compiler.
> +</p>
> +
> +
> +<h3><a name="C_Formatting">Formatting Conventions</a></h3>
> +
> +
> +<h4><a name="Line">Line Length</a></h4>
> +
> +<p>Lines shall be at most 80 columns.</p>
> +
> +
> +<h4><a name="C_Names">Names</a></h4>
> +
> +<p>
> +Macros names should be in <code>ALL_CAPS</code>
> +when it's important to be aware that it's a macro
> +(e.g. accessors and simple predicates),
> +but in lowercase (e.g., <code>size_int</code>)
> +where the macro is a wrapper for efficiency
> +that should be considered as a function;
> +see messages
> +<a href="http://gcc.gnu.org/ml/gcc-patches/2000-09/msg00901.html">1</a>
> +and <a
> href="http://gcc.gnu.org/ml/gcc-patches/2000-09/msg00912.html">2</a>.
> +</p>
> +
> +<p>
> +Other names should be lower-case and separated by low_lines.
> +</p>
> +
> +
> +<h4><a name="Expressions">Expressions</a></h4>
> +
> +<p>
> +Code in GCC should use the following formatting conventions:
> +</p>
> +
> +<table cellpadding="4">
> +<tr>
> +  <th align="left">For</th>
> +  <th align="right">Use...</th><th align="left">...instead of</th>
> +</tr><tr>
> +  <td align="left">logical not</td>
> +  <td align="right"><code>!x</code></td><td><code>! x</code></td>
> +</tr><tr>
> +  <td align="left">bitwise complement</td>
> +  <td align="right"><code>~x</code></td><td><code>~ x</code></td>
> +</tr><tr>
> +  <td align="left">unary minus</td>
> +  <td align="right"><code>-x</code></td><td><code>- x</code></td>
> +</tr><tr>
> +  <td align="left">cast</td>
> +  <td align="right"><code>(foo) x</code></td>
> +  <td><code>(foo)x</code></td>
> +</tr><tr>
> +  <td align="left">pointer dereference</td>
> +  <td align="right"><code>*x</code></td>
> +  <td><code>* x</code></td>
> +</tr>
> +</table>
> +
> +
> +<h4><a name="Calls">Function Calls</a></h4>
> +
> +<p>
> +All current GCC code uses a space between the function name
> +and the left parenthesis in a function call.
> +Essentially all C++ code omits that space,
> +which is more consistent with C++ syntax.
> +For the present we will retain the space.
> +It is possible that in the future we will switch the code with a flag day.
> +</p>
> +
> +
> +<h2><a name="Cxx_Conventions">C++ Language Conventions</a></h2>
> +
> +<p>
> +The following conventions apply only to C++.
> +</p>
> +
> +<p>
> +These conventions will change over time,
> +but changing them requires that a convincing rationale.
> +</p>
> +
> +
> +<h3><a name="Cxx_Language">Language Use</a></h3>
> +
> +<p>
> +C++ is a complex language,
> +and we strive to use it in a manner that is not surprising.
> +So, the primary rule is to be reasonable.
> +Use a language feature in known good ways.
> +If you need to use a feature in an unusual way,
> +or a way that violates the "should" rules below,
> +seek guidance, review and feedback from the wider community.
> +</p>
> +
> +<p>
> +All use of C++ features
> +is subject to the decisions of the maintainers of the relevant components.
> +(This restates something that is always true for gcc,
> +which is that
> +component maintainers make the final decisions about those components.)
> +</p>
> +
> +<h4><a name="Variable">Variable Definitions</a></h4>
> +
> +<p>
> +Variables should be defined at the point of first use,
> +rather than at the top of the function.
> +The existing code obviously does not follow that rule,
> +so variables may be defined at the top of the function,
> +as in C90.
> +</p>
> +
> +<p>
> +Variables may be simultaneously defined and tested in control expressions.
> +</p>
> +
> +<p>
> +<a href="codingrationale.html#variables">Rationale and Discussion</a>
> +</p>
> +
> +
> +<h4><a name="Struct_Use">Struct Definitions</a></h4>
> +
> +<p>
> +Use the <code>struct</code> keyword for
> +<a href="http://en.wikipedia.org/wiki/Plain_old_data_structure">
> +plain old data (POD)</a> types.
> +</p>
> +
> +<p>
> +<a href="codingrationale.html#struct">Rationale and Discussion</a>
> +</p>
> +
> +<h4><a name="Class_Use">Class Definitions</a></h4>
> +
> +<p>
> +Use the <code>class</code> keyword for
> +<a href="http://en.wikipedia.org/wiki/Plain_old_data_structure">
> +non-POD</a> types.
> +</p>
> +
> +<p>
> +A non-POD type will often (but not always)
> +have a declaration of a
> +<a href="http://en.wikipedia.org/wiki/Special_member_functions">
> +special member function</a>.
> +If any one of these is declared,
> +then all should be either declared
> +or have an explicit comment saying that the default is intended.
> +</p>
> +
> +<p>
> +Single inheritance is permitted.
> +Use public inheritance to describe interface inheritance,
> +i.e. 'is-a' relationships.
> +Use private and protected inheritance
> +to describe implementation inheritance.
> +Implementation inheritance can be expediant,
> +but think twice before using it in code
> +intended to last a long time.
> +</p>
> +
> +<p>
> +You should not use multiple inheritance.
> +</p>
> +
> +<p>
> +Think carefully about the size and performance impact
> +of virtual functions and virtual bases
> +before using them.
> +</p>
> +
> +<p>
> +Prefer to make data members private.
> +</p>
> +
> +<p>
> +<a href="codingrationale.html#class">Rationale and Discussion</a>
> +</p>
> +
> +
> +<h4><a name="Constructors">Constructors and Destructors</a></h4>
> +
> +<p>
> +All constructors should initialize data members
> +in the member initializer list rather than in the body of the constructor.
> +</p>
> +
> +<p>
> +A class with virtual functions or virtual bases
> +should have a virtual destructor.
> +</p>
> +
> +<p>
> +<a href="codingrationale.html#constructors">Rationale and Discussion</a>
> +</p>
> +
> +<h4><a name="Conversions">Conversions</a></h4>
> +
> +<p>
> +Single argument constructors should nearly always be declared explicit.
> +</p>
> +
> +<p>
> +Conversion operators should be avoided.
> +</p>
> +
> +<p>
> +<a href="codingrationale.html#conversions">Rationale and Discussion</a>
> +</p>
> +
> +
> +<h4><a name="Over_Func">Overloading Functions</a></h4>
> +
> +<p>
> +Overloading functions is permitted,
> +but take care to ensure that overloads are not surprising,
> +i.e. semantically identical or at least very similar.
> +Virtual functions should not be overloaded.
> +</p>
> +
> +<p>
> +<a href="codingrationale.html#overfunc">Rationale and Discussion</a>
> +</p>
> +
> +
> +<h4><a name="Over_Oper">Overloading Operators</a></h4>
> +
> +<p>
> +Overloading operators is permitted,
> +but take care to ensure that overloads are not surprising.
> +Some unsurprising uses are
> +in the implementation of numeric types and
> +in following the C++ Standard Library's conventions.
> +In addition, overloaded operators, excepting the call operator,
> +should not be used for expensive implementations.
> +</p>
> +
> +<p>
> +<a href="codingrationale.html#overoper">Rationale and Discussion</a>
> +</p>
> +
> +
> +<h4><a name="Default">Default Arguments</a></h4>
> +
> +<p>
> +Default arguments are another type of function overloading,
> +and the same rules apply.
> +Default arguments must always be POD values, i.e. may not run
> constructors.
> +Virtual functions should not have default arguments.
> +</p>
> +
> +<p>
> +<a href="codingrationale.html#default">Rationale and Discussion</a>
> +</p>
> +
> +
> +<h4><a name="Cxx_Inlining">Inlining Functions</a></h4>
> +
> +<p>
> +Constructors and destructors, even those with empty bodies,
> +are often much larger than programmers expect.
> +Prefer non-inline versions unless you have evidence
> +that the inline version is smaller or has a significant performance
> impact.
> +</p>
> +
> +
> +<h4><a name="Template_Use">Templates</a></h4>
> +
> +<p>
> +To avoid excessive compiler size,
> +consider implementing non-trivial templates
> +on a non-template base class with <code>void*</code> parameters.
> +</p>
> +
> +
> +<h4><a name="Namespace_Use">Namespaces</a></h4>
> +
> +<p>
> +Namespaces are encouraged.
> +All separable libraries should have a unique global namespace.
> +All individual tools should have a unique global namespace.
> +Nested include directories names should map to nested namespaces when
> possible.
> +</p>
> +
> +<p>
> +Header files should have neither <code>using</code> directives
> +nor namespace-scope <code>using</code> declarations.
> +</p>
> +
> +<p>
> +There is no alternative to <code>using</code> declarations
> +in class definitions to manage names within an inheritance hierarchy,
> +so they are necessarily permitted.
> +</p>
> +
> +<p>
> +<a href="codingrationale.html#namespaces">Rationale and Discussion</a>
> +</p>
> +
> +<h4><a name="RTTI">RTTI and <code>dynamic_cast</code></a></h4>
> +
> +<p>
> +Run-time type information (RTTI) is permitted
> +when certain non-default <code>--enable-checking</code> options are
> enabled,
> +so as to allow checkers to report dynamic types.
> +However, by default, RTTI is not permitted
> +and the compiler must build cleanly with <code>-fno-rtti</code>.
> +</p>
> +
> +<p>
> +<a href="codingrationale.html#RTTI">Rationale and Discussion</a>
> +</p>
> +
> +
> +<h4><a name="Casts">Other Casts</a></h4>
> +
> +<p>
> +C-style casts should not be used.
> +Instead, use C++-style casts.
> +</p>
> +
> +<p>
> +<a href="codingrationale.html#casts">Rationale and Discussion</a>
> +</p>
> +
> +
> +<h4><a name="Exceptions">Exceptions</a></h4>
> +
> +<p>
> +Exceptions and throw specifications are not permitted
> +and the compiler must build cleanly with <code>-fno-exceptions</code>.
> +</p>
> +
> +<p>
> +<a href="codingrationale.html#exceptions">Rationale and Discussion</a>
> +</p>
> +
> +
> +<h4><a name="Standard_Library">The Standard Library</a></h4>
> +
> +<p>
> +Use of the standard library is permitted.
> +Note, however, that it is currently not usable with garbage collected
> data.
> +</p>
> +
> +<p>
> +For compiler messages, indeed any text that needs i18n,
> +should continue to use the existing facilities.
> +</p>
> +
> +<p>
> +For long-term code, at least for now,
> +we will continue to use <code>printf</code> style I/O
> +rather than <code>&lt;iostream&gt;</code> style I/O.
> +For quick debugging code,
> +<code>&lt;iostream&gt;</code> is permitted.
> +</p>
> +
> +<p>
> +<a href="codingrationale.html#stdlib">Rationale and Discussion</a>
> +</p>
> +
> +
> +<h3><a name="Cxx_Formatting">Formatting Conventions</a></h3>
> +
> +
> +<h4><a name="Cxx_Names">Names</a></h4>
> +
> +<p>
> +When structs and/or classes have member functions,
> +prefer to name data members with a trailing underscore.
> +</p>
> +
> +<p>
> +Template parameter names should use CamelCase,
> +following the C++ Standard.
> +</p>
> +
> +<p>
> +<a href="codingrationale.html#stdlib">Rationale and Discussion</a>
> +</p>
> +
> +
> +<h4><a name="Struct_Form">Struct Definitions</a></h4>
> +
> +<p>
> +Note that the rules for classes do not apply to structs.
> +Structs continue to behave as before.
> +</p>
> +
> +
> +<h4><a name="Class_Form">Class Definitions</a></h4>
> +
> +<p>
> +If the entire class definition fits on a single line, put it on a single
> line.
> +Otherwise, use the following rules.
> +</p>
> +
> +<p>
> +Indent protection labels by one space.
> +</p>
> +
> +<p>
> +Indent class members by two spaces.
> +</p>
> +
> +<p>
> +Prefer to put the entire class head on a single line.
> +</p>
> +
> +<blockquote><pre><code>
> +class gnuclass : base {
> +</code></pre></blockquote>
> +
> +<p>
> +Otherwise, start the colon of the base list at the beginning of a line.
> +</p>
> +
> +<blockquote><pre><code>
> +class a_rather_long_class_name
> +: with_a_very_long_base_name, and_another_just_to_make_life_hard
> +{
> +  int member;
> +};
> +</code></pre></blockquote>
> +
> +<p>
> +If the base clause exceeds one line,
> +move overflowing initializers to the next line and indent by two spaces.
> +</p>
> +
> +<blockquote><pre><code>
> +class gnuclass
> +: base1 &lt;template_argument1&gt;, base2 &lt;template_argument1&gt;,
> +  base3 &lt;template_argument1&gt;, base4 &lt;template_argument1&gt;
> +{
> +  int member;
> +};
> +</code></pre></blockquote>
> +
> +<p>
> +When defining a class,
> +</p>
> +<ul>
> +<li>first define all public types,</li>
> +<li>then define all non-public types,</li>
> +<li>then declare all public constructors,</li>
> +<li>then declare the public destructor,</li>
> +<li>then declare all public member functions,</li>
> +<li>then declare all public member variables,</li>
> +<li>then declare all non-public constructors,</li>
> +<li>then declare the non-public destructor,</li>
> +<li>then declare all non-public member functions, and</li>
> +<li>then declare all non-public member variables.</li>
> +</ul>
> +
> +<p>
> +Semantic constraints may require a different declaration order,
> +but seek to minimize the potential confusion.
> +</p>
> +
> +<p>
> +Close a class definition
> +with a right brace, semicolon, optional closing comment, and a new line.
> +</p>
> +
> +<blockquote><pre><code>
> +} // class gnuclass
> +</code></pre></blockquote>
> +
> +
> +<h4><a name="Member_Form">Class Member Definitions</a></h4>
> +
> +<p>
> +Define all members outside the class definition.
> +That is, there are no function bodies or member initializers
> +inside the class definition.
> +</p>
> +
> +<p>
> +Prefer to put the entire member head on a single line.
> +</p>
> +
> +<blockquote><pre><code>
> +gnuclass::gnuclass() : base_class()
> +{
> +  ...
> +};
> +</code></pre></blockquote>
> +
> +<p>
> +When that is not possible,
> +place the colon of the initializer clause at the beginning of a line.
> +</p>
> +
> +<blockquote><pre><code>
> +gnuclass::gnuclass()
> +: base1(), base2(), member1(), member2(), member3(), member4()
> +{
> +  ...
> +};
> +</code></pre></blockquote>
> +
> +<p>
> +If the initializer clause exceeds one line,
> +move overflowing initializers to the next line and indent by two spaces.
> +</p>
> +
> +<blockquote><pre><code>
> +gnuclass::gnuclass()
> +: base1(some_expression), base2(another_expression),
> +  member1(my_expressions_everywhere)
> +{
> +  ...
> +};
> +</code></pre></blockquote>
> +
> +<p>
> +If a C++ function name is long enough
> +to cause the first function parameter with its type to exceed 80
> characters,
> +it should appear on the next line indented four spaces.
> +</p>
> +
> +<blockquote><pre><code>
> +void
> +very_long_class_name::very_long_function_name(
> +    very_long_type_name arg)
> +{
> +</code></pre></blockquote>
> +
> +<p>
> +Sometimes the class qualifier and function name together exceed 80
> characters.
> +In this case, break the line before the <code>::</code> operator.
> +We may wish to do so pre-emptively for all class member functions.
> +</p>
> +
> +<blockquote><pre><code>
> +void
> +very_long_template_class_name &lt;with, a, great, many, arguments&gt;
> +::very_long_function_name(
> +    very_long_type_name arg)
> +{
> +</code></pre></blockquote>
> +
> +
> +<h4><a name="Template_Form">Templates</a></h4>
> +
> +<p>
> +A declaration following a template parameter list
> +should not have additional indentation.
> +</p>
> +
> +<p>
> +Prefer <code>typename</code> over <code>class</code>
> +in template parameter lists.
> +</p>
> +
> +
> +<h4><a name="ExternC">Extern "C"</a></h4>
> +
> +<p>
> +Prefer an <code>extern "C"</code> block to a declaration qualifier.
> +</p>
> +
> +<p>
> +Open an <code>extern "C"</code> block with the left brace on the same
> line.
> +</p>
> +
> +<blockquote><pre><code>
> +extern "C" {
> +</code></pre></blockquote>
> +
> +<p>
> +Close an <code>extern "C"</code> block
> +with a right brace, optional closing comment, and a new line.
> +</p>
> +
> +<blockquote><pre><code>
> +} // extern "C"
> +</code></pre></blockquote>
> +
> +<p>
> +Definitions within the body of a namespace are not indented.
> +</p>
> +
> +<h4><a name="Namespace_Form">Namespaces</a></h4>
> +
> +<p>
> +Open a namespace with the namespace name
> +followed by a left brace and a new line.
> +</p>
> +
> +<blockquote><pre><code>
> +namespace gnutool {
> +</code></pre></blockquote>
> +
> +<p>
> +Close a namespace
> +with a right brace, optional closing comment, and a new line.
> +</p>
> +
> +<blockquote><pre><code>
> +} // namespace gnutool
> +</code></pre></blockquote>
> +
> +<p>
> +Definitions within the body of a namespace are not indented.
> +</p>
> +
> +
>  </body>
>  </html>
> Index: codingrationale.html
> ===================================================================
> RCS file: codingrationale.html
> diff -N codingrationale.html
> --- /dev/null   1 Jan 1970 00:00:00 -0000
> +++ codingrationale.html        18 Jun 2012 22:04:49 -0000
> @@ -0,0 +1,386 @@
> +
> +<head>
> +<title>GCC Coding Conventions Rationale and Discussion</title>
> +</head>
> +
> +<body>
> +<h1>GCC Coding Conventions Rationale and Discussion</h1>
> +
> +<h2>C and C++ Language Conventions</h2>
> +
> +<h3>Language Use</h3>
> +
> +<h4>Inlining Functions</h4>
> +
> +<p>
> +Inlining functions has a potential cost in object size,
> +working set size, compile time, and debuggablity.
> +These costs should not be borne without some evidence
> +that the inlining pays for itself.
> +</p>
> +
> +
> +<h2>C++ Language Conventions</h2>
> +
> +<h3>Language Use</h3>
> +
> +<h4><a name="variables">Variable Definitions</a></h4>
> +
> +<p>
> +Defining variables when they are first needed
> +reduces the cognitive burden on the programmer.
> +It also eases converting common sub-expressions
> +into a defined and reused variable.
> +</p>
> +
> +<p>
> +Defining and testing variables in control expressions
> +has the same advantages as above.
> +In addition, it restricts the scope of the variable
> +to the region in which it is known to be sensible.
> +</p>
> +
> +<blockquote><pre><code>
> +if (info *q = get_any_available_info ()) {
> +  // q is known to be non-NULL, and so do useful processing.
> +}
> +</code></pre></blockquote>
> +
> +
> +<h4><a name="struct">Struct Definitions</a></h4>
> +
> +<p>
> +In the C++ standard,
> +structs and classes differ only in the default access rules.
> +We prefer to use these two keywords to signal more information.
> +</p>
> +
> +<p>
> +Note that under this definition,
> +structs may have member functions.
> +This freedom is useful for transitional code.
> +</p>
> +
> +
> +<h4><a name="class">Class Definitions</a></h4>
> +
> +<p>
> +Forgetting to write a special member function is a known programming
> problem.
> +Some authors recommend always defining all special member functions.
> +Such classes are less efficient.
> +First, these definitions may prevent the compiler
> +from passing the class in a register.
> +Second, these definitions may prevent the compiler
> +from using more efficient methods for copying.
> +Adding a comment that the default is intended
> +preserves the performance while ensuring that
> +the function was not forgotten.
> +</p>
> +
> +<p>
> +FIXME: Discussion of deleting inappropraite special members.
> +Classes generally are either value classes or identity classes.
> +Copy constructors and assignment operators are fine for value classes.
> +They are often not appropriate to identity classes.
> +These classes should delete, or disable, these functions.
> +Marking such functions as follows
> +will enable compiling against C++03,
> +and later modifying them for C++11.
> +</p>
> +
> +<blockquote><pre><code>
> +TypeName(const TypeName&amp;) /*DELETED*/;
> +void operator=(const TypeName&amp;) /*DELETED*/;
> +</code></pre></blockquote>
> +
> +<p>
> +Multiple inheritance is confusing and rarely useful.
> +When it is needed though, there may be no substitute.
> +Seek guidance, review and feedback from the wider community.
> +</p>
> +
> +<p>
> +Using virtual functions increases the size of instances of the class
> +by at least one pointer.
> +In heavily allocated types, such as trees, GIMPLE or RTL,
> +this size increase could have adverse performance impacts.
> +On the other hand,
> +virtual functions can often reduce the size of instances
> +by binding information into the virtual tables and the virtual functions.
> +For example, various type tags need not be present.
> +Other attributes can be inferred
> +from type and more general information,
> +or from extending the class hierarchy at the leaves.
> +So, even though trees are heavily allocated,
> +it remains to be seen whether virtual functions would increase the size.
> +Therefore virtual functions should be added in heavily allocated classes
> +only after size and performance studies.
> +However, virtual functions are acceptable where we use hooks today,
> +as they are already essentially virtual tables.
> +</p>
> +
> +<p>
> +There are good reasons to make private
> +all data members of non-POD classes.
> +However, in converting from C to C++,
> +there is a necessary transition that has public data members.
> +</p>
> +
> +
> +<h4><a name="constructors">Constructors and Destructors</a></h4>
> +
> +<p>
> +The compiler implicitly initializes all non-POD fields.
> +Any initialization in the body of the constructor implies extra work.
> +</p>
> +
> +<p>
> +Polymorphic classes without a virtual destructor
> +are almost certainly incorrect.
> +</p>
> +
> +<h4><a name="conversions">Conversions</a></h4>
> +
> +<p>
> +C++ uses single-argument constructors for implicit type conversion.
> +Wide use of implicit conversion can cause some very surprising results.
> +</p>
> +
> +<p>
> +C++03 has no explicit conversion operators,
> +and hence using them cannot avoid suprises.
> +Wait for C++11.
> +</p>
> +
> +
> +<h4><a name="overfunc">Overloading Functions</a></h4>
> +
> +<p>
> +Function overloading can be confusing.
> +However, in some cases introducing new function names adds little value,
> +as in the current distinction
> +between <code>build_index_type</code> and <code>build_index_2_type</code>.
> +</p>
> +
> +<p>
> +The essential problem is to use overloading in a way that
> +improves conciseness without introducing confusion.
> +To that end, consider the following advice.
> +</p>
> +
> +<p>
> +You may overload if the overloaded name supports an action notion.
> +For example, the C++ standard's notion of swap.
> +</p>
> +
> +<p>
> +You may <em>not</em> overload
> +when implicit conversions among argument types may yield unintended
> effects.
> +For example,
> +</p>
> +
> +<blockquote><pre><code>
> +void swizzle (int arg);
> +void swizzle (const char *arg);
> +... swizzle (NULL); ...
> +</code></pre></blockquote>
> +
> +<p>
> +results in an unintended call to the <code>int</code> overload on some
> systems.
> +In practice, the problem that this restriction addresses
> +arises more from bad user-defined implicit conversion operators.
> +See ISO C++
> +<a
> href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2437.pdf">
> +N2437</a>
> +and
> +ISO C++
> +<a
> href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2514.html">
> +N2514</a>.
> +</p>
> +
> +<p>
> +You may overload if a single argument, in a single position,
> +has multiple representations. For example,
> +</p>
> +
> +<blockquote><pre><code>
> +void append (const char *str);
> +void append (std::string str);
> +</code></pre></blockquote>
> +
> +<p>
> +You may <em>not</em> overload
> +if more than one argument constitutes the representation of some data
> notion.
> +For example, in
> +</p>
> +
> +<blockquote><pre><code>
> +void register (int house, const char *street, int zipcode);
> +</code></pre></blockquote>
> +
> +<p>
> +the arguments are a representation of addresses.
> +Instead, the overload should be on addresses.
> +</p>
> +
> +<blockquote><pre><code>
> +void register(const Address &amp;addr);
> +</code></pre></blockquote>
> +
> +<p>
> +This restriction cannot apply to constructors,
> +where the whole point is to collect representational data.
> +</p>
> +
> +<blockquote><pre><code>
> +Address::Address (int house, const char *street, int zipcode);
> +</code></pre></blockquote>
> +
> +<p>
> +Notwithstanding the restrictions above, you may overload to detect errors.
> +That is, if unsigned numbers are good, but signed numbers are bad,
> +you could overload
> +</p>
> +
> +<blockquote><pre><code>
> +void munch (unsigned int arg);
> +void munch (int arg);
> +</code></pre></blockquote>
> +
> +<p>
> +and simply not define the signed int version.
> +Anyone using it would get a link-time error.
> +(The C++11 standard has a syntax
> +that enables compile-time detection of the problem.)
> +</p>
> +
> +
> +<h4><a name="overoper">Overloading Operators</a></h4>
> +
> +<p>
> +Using <code>[]</code> to index a vector is unsurprising,
> +but using <code>[]</code> to query a database over a network
> +is bound to cause performance problems.
> +</p>
> +
> +
> +<h4><a name="default">Default Arguments</a></h4>
> +
> +<p>
> +Expensive default arguments can cause hard-to-identify performance
> problems.
> +</p>
> +
> +<p>
> +Default arguments cause confusion
> +when attempting to take the address of a function.
> +They clause client code taking the address of a function
> +to break when a default argument is replaced by a specialized overload.
> +So, default arguments should generally not be used
> +in customer-facing interfaces.
> +Consider function overloading instead.
> +</p>
> +
> +
> +<h4><a name="namespace">Namespaces</a></h4>
> +
> +<p>
> +Putting <code>using</code> directives
> +or namespace-scope <code>using</code> declarations
> +into header files can change client code in surprising ways.
> +</p>
> +
> +<p>
> +Using them within an implementation file can help conciseness.
> +</p>
> +
> +
> +<h4><a name="RTTI">RTTI and <code>dynamic_cast</code></a></h4>
> +
> +<p>
> +Disabling RTTI will save space in the compiler.
> +</p>
> +
> +<p>
> +Checking the type of a class at runtime usually indicates a design
> problem.
> +If you need classes to behave differently at runtime, use a virtual
> method.
> +If you need to know the type of a class for some other reason,
> +use an enum or a virtual member function
> +that coverts a pointer to the more derived class.
> +For example,
> +</p>
> +
> +<blockquote><pre><code>
> +common_type *p = ....;
> +if (specific_type *q = p-&gt;to_specific ()) {
> +  // We have and can use a specific_type pointed to by q.
> +}
> +</code></pre></blockquote>
> +
> +<h4><a name="casts">Other Casts</a></h4>
> +
> +<p>
> +C++-style casts are very explicit in the intended transformation.
> +Making intent clear avoids bugs and helps with other programmers.
> +</p>
> +
> +
> +<h4><a name="exceptions">Exceptions</a></h4>
> +
> +<p>
> +The current compiler code is not exception safe.
> +</p>
> +
> +<p>
> +Disabling exceptions will permit
> +the compiler itself to be slightly more optimized.
> +</p>
> +
> +<p>
> +Aborting the compiler is a reasonable response to unexpected problems.
> +</p>
> +
> +<p>
> +We would like the compiler to be exception safe,
> +to permit reconsideration of the exception convention.
> +This change would require a significant change in style,
> +adopting "resource acquisition is initialization" (RAII).
> +We would be using
> +<code>shared_ptr</code> (from TR1's <code>&lt;memory&gt;</code>)
> +or <code>unique_ptr</code> (from C++11).
> +</p>
> +
> +<h4><a name="stdlib">The Standard Library</a></h4>
> +
> +<p>
> +At present, C++ provides no great advantage for i18n.
> +GCC does type checking for <code>printf</code> arguments,
> +so the type insecurity of <code>printf</code> is moot,
> +but the clarity in layout persists.
> +For quick debugging output, &lt;iostream&gt; requires less work.
> +</p>
> +
> +<h3>Formatting Conventions</h3>
> +
> +<h4><a href="names">Names</a></h4>
> +
> +<p>
> +Naming data members with a trailing underscore
> +highlights the extra overhead of access to fields over local variables.
> +Think of the trailing underscore
> +like you would Pascal's postfix <code>^</code> dereference operator.
> +</p>
> +
> +<p>
> +When using the above convention,
> +the constructor parameter names
> +and getter member function names
> +can use the more concise non-underscore form.
> +</p>
> +
> +</body>
> +</html>
>
> --
> Lawrence Crowl
Joseph S. Myers - June 25, 2012, 7:05 p.m.
On Mon, 25 Jun 2012, Diego Novillo wrote:

> [ Added doc maintainers in CC ]
> 
> While I'm not particularly interested in the details of the coding
> conventions, I am interested in getting them in getting them installed
> before we merge cxx-conversion to trunk.
> 
> Joseph, Gerald, do we have a process for accepting changes to coding
> conventions?

I suggest sending smaller (so easier to review) patches that are concrete 
and avoid speculation about possible future changes.

> > +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#C_Options">Compiler Options</a><br />

I don't like this repeated &nbsp; presentational markup; use appropriate 
logical markup instead.

> > +<p>
> > +We will periodically pick a stable version of GCC,
> > +and require that that version of GCC be able to build
> > +all versions of GCC up to and including the next stable version.
> > +E.g., we may decide that all newer versions of GCC
> > +should be buildable with GCC 4.3.5.

The current version required is more important than speculation about 
future changes.  E.g., say that code must build with GCC 4.1 and later.

> > +<h4><a name="Assertions">Assertions</a></h4>
> > +
> > +<p>Code should use <code>gcc_assert(EXPR)</code> to check invariants.
> > +Use <code>gcc_unreachable()</code> to mark places that should never be
> > +reachable (such as an unreachable <code>default</code> case of a
> > +switch).  Do not use <code>gcc_assert(0)</code> for such purposes, as
> > +<code>gcc_unreachable</code> gives the compiler more information.  The
> > +assertions are enabled unless explicitly configured off with
> > +<code>--enable-checking=none</code>.  Do not use <code>abort</code>.
> > +User input should never be validated by either <code>gcc_assert</code>
> > +or <code>gcc_unreachable</code>.  If the checks are expensive or the
> > +compiler can reasonably carry on after the error, they may be
> > +conditioned on <code>--enable-checking</code>.</p>

I don't think any of this is new - perhaps you could separate 
rearrangement from the actual changes and C++ conventions?

> > +<h4><a name="Calls">Function Calls</a></h4>
> > +
> > +<p>
> > +All current GCC code uses a space between the function name
> > +and the left parenthesis in a function call.
> > +Essentially all C++ code omits that space,
> > +which is more consistent with C++ syntax.
> > +For the present we will retain the space.
> > +It is possible that in the future we will switch the code with a flag day.
> > +</p>

Avoid speculation.  Avoid duplicating the GNU Coding Standards.  
Formatting can be assumed to follow the GNU Coding Standards except where 
they are meaningless for C++ or something explicitly overrides them.

> > +<p>
> > +Think carefully about the size and performance impact
> > +of virtual functions and virtual bases
> > +before using them.
> > +</p>

Explain in more detail what the size and performance impact is for people 
not familiar with the details of how C++ features are implemented.

> > +<p>
> > +Indent protection labels by one space.
> > +</p>
> > +
> > +<p>
> > +Indent class members by two spaces.

Do all the listed indentation rules correspond to what a <TAB> will do by 
default when editing C++ code in GNU Emacs?  If not, we have conflicting 
notions of GNU C++ indentation conventions.
Lawrence Crowl - June 25, 2012, 10:17 p.m.
On 6/25/12, Joseph S. Myers <joseph@codesourcery.com> wrote:
> On Mon, 25 Jun 2012, Diego Novillo wrote:
> > [ Added doc maintainers in CC ]
> >
> > While I'm not particularly interested in the details of the
> > coding conventions, I am interested in getting them in getting
> > them installed before we merge cxx-conversion to trunk.
> >
> > Joseph, Gerald, do we have a process for accepting changes to
> > coding conventions?
>
> I suggest sending smaller (so easier to review) patches that are
> concrete and avoid speculation about possible future changes.

The speculative parts come from the wiki.  Unless I had specific
reason to remove them, I left them.

> > > +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#C_Options">Compiler Options</a><br />
>
> I don't like this repeated &nbsp; presentational markup; use
> appropriate logical markup instead.

Done.

> > > +<p>
> > > +We will periodically pick a stable version of GCC,
> > > +and require that that version of GCC be able to build
> > > +all versions of GCC up to and including the next stable version.
> > > +E.g., we may decide that all newer versions of GCC
> > > +should be buildable with GCC 4.3.5.
>
> The current version required is more important than speculation
> about future changes.  E.g., say that code must build with GCC
> 4.1 and later.

After some off-line discussion with Diego, I have removed some of
text in this area.  It now focuses on being portable, rather than
on arbitrary version numbers.

> > > +<h4><a name="Assertions">Assertions</a></h4>
> > > +
> > > +<p>Code should use <code>gcc_assert(EXPR)</code> to check invariants.
> > > +Use <code>gcc_unreachable()</code> to mark places that should never be
> > > +reachable (such as an unreachable <code>default</code> case of a
> > > +switch).  Do not use <code>gcc_assert(0)</code> for such purposes, as
> > > +<code>gcc_unreachable</code> gives the compiler more information.  The
> > > +assertions are enabled unless explicitly configured off with
> > > +<code>--enable-checking=none</code>.  Do not use <code>abort</code>.
> > > +User input should never be validated by either <code>gcc_assert</code>
> > > +or <code>gcc_unreachable</code>.  If the checks are expensive or the
> > > +compiler can reasonably carry on after the error, they may be
> > > +conditioned on <code>--enable-checking</code>.</p>
>
> I don't think any of this is new - perhaps you could separate
> rearrangement from the actual changes and C++ conventions?

The section titles are new, but the text itself is not.  There did
not seem to be a reasonable way to separate the rearrangment from
the new context in which it was placed.

> > > +<h4><a name="Calls">Function Calls</a></h4>
> > > +
> > > +<p>
> > > +All current GCC code uses a space between the function name
> > > +and the left parenthesis in a function call.
> > > +Essentially all C++ code omits that space,
> > > +which is more consistent with C++ syntax.
> > > +For the present we will retain the space.
> > > +It is possible that in the future we will switch the code with a flag day.
> > > +</p>
>
> Avoid speculation.  Avoid duplicating the GNU Coding Standards.
> Formatting can be assumed to follow the GNU Coding Standards
> except where they are meaningless for C++ or something explicitly
> overrides them.

That paragraph came from the wiki.  I have removed it.

> > > +<p>
> > > +Think carefully about the size and performance impact
> > > +of virtual functions and virtual bases
> > > +before using them.
> > > +</p>
>
> Explain in more detail what the size and performance impact is
> for people not familiar with the details of how C++ features
> are implemented.

I have added a bit more in the rationale, reached through the link
at the end of that section.

> > > +<p>
> > > +Indent protection labels by one space.
> > > +</p>
> > > +
> > > +<p>
> > > +Indent class members by two spaces.
>
> Do all the listed indentation rules correspond to what a <TAB>
> will do by default when editing C++ code in GNU Emacs?  If not,
> we have conflicting notions of GNU C++ indentation conventions.

I have no idea.  I don't use emacs.  The two-space rule for members
comes from the wiki.  The one-space rule for protection labels is
common practice.  If folks want something else, changes are fine
with me.

I have also made a few other edits requested offline by Benjamin
Kosnik.
Magnus Fromreide - June 27, 2012, 12:35 a.m.
On Mon, 2012-06-25 at 15:17 -0700, Lawrence Crowl wrote:
> On 6/25/12, Joseph S. Myers <joseph@codesourcery.com> wrote:
> > On Mon, 25 Jun 2012, Diego Novillo wrote:
> > > [ Added doc maintainers in CC ]
> > >

> I have added a bit more in the rationale, reached through the link
> at the end of that section.
> 
> > > > +<p>
> > > > +Indent protection labels by one space.
> > > > +</p>
> > > > +
> > > > +<p>
> > > > +Indent class members by two spaces.
> >
> > Do all the listed indentation rules correspond to what a <TAB>
> > will do by default when editing C++ code in GNU Emacs?  If not,
> > we have conflicting notions of GNU C++ indentation conventions.
> 
> I have no idea.  I don't use emacs.  The two-space rule for members
> comes from the wiki.  The one-space rule for protection labels is
> common practice.  If folks want something else, changes are fine
> with me.

Two spaces for members is common practice with GNU, and it seems to be
used for libstdc++.

One space for protection labels is not something I have heard of before
and libstdc++ uses no indentation for them.

A freshly started emacs also doesn't indent access labels.

I do think there is some value in using the same coding style for
libstdc++ and the compiler.

/MF
Miles Bader - June 27, 2012, 4:50 a.m.
Magnus Fromreide <magfr@lysator.liu.se> writes:
> Two spaces for members is common practice with GNU, and it seems to be
> used for libstdc++.
>
> One space for protection labels is not something I have heard of before
> and libstdc++ uses no indentation for them.
>
> A freshly started emacs also doesn't indent access labels.

Yeah, zero indentation (or rather, "aligned with the surrounding brace
level", e.g. for nested structures/classes) is certainly the defacto
GNU standard for C++ "access labels" (private:, etc).

There seems no reason for GCC to be different.

-miles
Richard Guenther - June 27, 2012, 8:48 a.m.
On Wed, Jun 27, 2012 at 2:35 AM, Magnus Fromreide <magfr@lysator.liu.se> wrote:
> On Mon, 2012-06-25 at 15:17 -0700, Lawrence Crowl wrote:
>> On 6/25/12, Joseph S. Myers <joseph@codesourcery.com> wrote:
>> > On Mon, 25 Jun 2012, Diego Novillo wrote:
>> > > [ Added doc maintainers in CC ]
>> > >
>
>> I have added a bit more in the rationale, reached through the link
>> at the end of that section.
>>
>> > > > +<p>
>> > > > +Indent protection labels by one space.
>> > > > +</p>
>> > > > +
>> > > > +<p>
>> > > > +Indent class members by two spaces.
>> >
>> > Do all the listed indentation rules correspond to what a <TAB>
>> > will do by default when editing C++ code in GNU Emacs?  If not,
>> > we have conflicting notions of GNU C++ indentation conventions.
>>
>> I have no idea.  I don't use emacs.  The two-space rule for members
>> comes from the wiki.  The one-space rule for protection labels is
>> common practice.  If folks want something else, changes are fine
>> with me.
>
> Two spaces for members is common practice with GNU, and it seems to be
> used for libstdc++.
>
> One space for protection labels is not something I have heard of before
> and libstdc++ uses no indentation for them.
>
> A freshly started emacs also doesn't indent access labels.
>
> I do think there is some value in using the same coding style for
> libstdc++ and the compiler.

I agree here.  It's the same we do for case labels.

Richard.

> /MF
>
Gabriel Dos Reis - June 27, 2012, 8:51 a.m.
[...]

| > Two spaces for members is common practice with GNU, and it seems to be
| > used for libstdc++.
| >
| > One space for protection labels is not something I have heard of before
| > and libstdc++ uses no indentation for them.
| >
| > A freshly started emacs also doesn't indent access labels.
| >
| > I do think there is some value in using the same coding style for
| > libstdc++ and the compiler.
| 
| I agree here.  It's the same we do for case labels.
| 
| Richard.

I think we reached total agreement :-)

-- Gaby
Chiheng Xu - June 27, 2012, 1:16 p.m.
On Tue, Jun 19, 2012 at 6:28 AM, Lawrence Crowl <crowl@google.com> wrote:
>  <p>Function prototypes for extern functions should only occur in
>  header files.  Functions should be ordered within source files to
>  minimize the number of function prototypes, by defining them before
> @@ -121,13 +208,13 @@
>  necessary, to break mutually recursive cycles.</p>
>

If you always put entry functions in the bottom of a source file, and
generically, always put upper layer functions below the lower layer
functions. Then probably there will be no need for function prototypes
in a source file.


> +<h4><a name="Namespace_Use">Namespaces</a></h4>
> +
> +<p>
> +Namespaces are encouraged.
> +All separable libraries should have a unique global namespace.
> +All individual tools should have a unique global namespace.
> +Nested include directories names should map to nested namespaces when
> possible.
> +</p>

Do all people have a consensus on the use of namespace ?

> +
> +<p>
> +Header files should have neither <code>using</code> directives
> +nor namespace-scope <code>using</code> declarations.
> +</p>
> +
> +<p>
> +There is no alternative to <code>using</code> declarations
> +in class definitions to manage names within an inheritance hierarchy,
> +so they are necessarily permitted.
> +</p>


> +<h4><a name="Exceptions">Exceptions</a></h4>
> +
> +<p>
> +Exceptions and throw specifications are not permitted
> +and the compiler must build cleanly with <code>-fno-exceptions</code>.
> +</p>
> +
> +<p>
> +<a href="codingrationale.html#exceptions">Rationale and Discussion</a>
> +</p>
> +
> +
> +<h4><a name="Standard_Library">The Standard Library</a></h4>
> +
> +<p>
> +Use of the standard library is permitted.
> +Note, however, that it is currently not usable with garbage collected
> data.
> +</p>
> +
> +<p>
> +For compiler messages, indeed any text that needs i18n,
> +should continue to use the existing facilities.
> +</p>
> +
> +<p>
> +For long-term code, at least for now,
> +we will continue to use <code>printf</code> style I/O
> +rather than <code>&lt;iostream&gt;</code> style I/O.
> +For quick debugging code,
> +<code>&lt;iostream&gt;</code> is permitted.
> +</p>

Is iostream really suitable or necessary for GCC ?
Have you think about writing another thinner interface , like Java's IO stream.
Lawrence Crowl - June 28, 2012, 1:37 a.m.
On 6/27/12, Gabriel Dos Reis <gdr@cs.tamu.edu> wrote:
>
> [...]
>
> | > Two spaces for members is common practice with GNU, and it seems to be
> | > used for libstdc++.
> | >
> | > One space for protection labels is not something I have heard of before
> | > and libstdc++ uses no indentation for them.
> | >
> | > A freshly started emacs also doesn't indent access labels.
> | >
> | > I do think there is some value in using the same coding style for
> | > libstdc++ and the compiler.
> |
> | I agree here.  It's the same we do for case labels.
> |
> | Richard.
>
> I think we reached total agreement :-)

I have changed the convention to not indent the protection label.
Lawrence Crowl - June 28, 2012, 1:49 a.m.
On 6/27/12, Chiheng Xu <chiheng.xu@gmail.com> wrote:
> On Jun 19, 2012, Lawrence Crowl <crowl@google.com> wrote:
> >  <p>Function prototypes for extern functions should only occur in
> >  header files.  Functions should be ordered within source files to
> >  minimize the number of function prototypes, by defining them before
> > @@ -121,13 +208,13 @@
> >  necessary, to break mutually recursive cycles.</p>
>
> If you always put entry functions in the bottom of a source file, and
> generically, always put upper layer functions below the lower layer
> functions. Then probably there will be no need for function prototypes
> in a source file.

This text is not a change.  I would prefer to not address changes
to it in this patch.

>> +<h4><a name="Namespace_Use">Namespaces</a></h4>
>> +
>> +<p>
>> +Namespaces are encouraged.
>> +All separable libraries should have a unique global namespace.
>> +All individual tools should have a unique global namespace.
>> +Nested include directories names should map to nested namespaces when
>> possible.
>> +</p>
>
> Do all people have a consensus on the use of namespace ?

Well, we really only know about objections, and I have not seen any.

>> +<p>
>> +Header files should have neither <code>using</code> directives
>> +nor namespace-scope <code>using</code> declarations.
>> +</p>
>> +
>> +<p>
>> +There is no alternative to <code>using</code> declarations
>> +in class definitions to manage names within an inheritance hierarchy,
>> +so they are necessarily permitted.
>> +</p>

You must have a draft copy.  That second paragraph is not in
the patch.

>> +<h4><a name="Standard_Library">The Standard Library</a></h4>
>> +
>> +<p>
>> +Use of the standard library is permitted.
>> +Note, however, that it is currently not usable with garbage collected
>> data.
>> +</p>
>> +
>> +<p>
>> +For compiler messages, indeed any text that needs i18n,
>> +should continue to use the existing facilities.
>> +</p>
>> +
>> +<p>
>> +For long-term code, at least for now,
>> +we will continue to use <code>printf</code> style I/O
>> +rather than <code>&lt;iostream&gt;</code> style I/O.
>> +For quick debugging code,
>> +<code>&lt;iostream&gt;</code> is permitted.
>> +</p>
>
> Is iostream really suitable or necessary for GCC ?

It is sometime suitable and not necessary.

> Have you think about writing another thinner interface, like
> Java's IO stream.

We probably should not implement yet another I/O interface.  We
should either use the existing GCC facilities, or use the standard
C/C++ facilities.  A third set would increase the learning curve.
Joseph S. Myers - June 28, 2012, 2:07 p.m.
On Wed, 27 Jun 2012, Lawrence Crowl wrote:

> >> +<h4><a name="Namespace_Use">Namespaces</a></h4>
> >> +
> >> +<p>
> >> +Namespaces are encouraged.
> >> +All separable libraries should have a unique global namespace.
> >> +All individual tools should have a unique global namespace.
> >> +Nested include directories names should map to nested namespaces when
> >> possible.
> >> +</p>
> >
> > Do all people have a consensus on the use of namespace ?
> 
> Well, we really only know about objections, and I have not seen any.

I certainly think namespaces are a useful feature to use in GCC (with a 
namespace for the gcc/ directory, or as you imply separate ones for the 
driver and the compilers proper, one for libcpp, one for each front end, 
etc.).

Patch

Index: codingconventions.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/codingconventions.html,v
retrieving revision 1.66
diff -u -u -r1.66 codingconventions.html
--- codingconventions.html	19 Feb 2012 00:45:34 -0000	1.66
+++ codingconventions.html	18 Jun 2012 22:04:49 -0000
@@ -1,4 +1,8 @@ 

 <head>
 <title>GCC Coding Conventions</title>
@@ -15,8 +19,56 @@ 
 code to follow these conventions, it is best to send changes to follow
 the conventions separately from any other changes to the code.</p>

+<p>
+<a href="#Documentation">Documentation</a><br />
+<a href="#ChangeLogs">ChangeLogs</a><br />
+<a href="#Portability">Portability</a><br />
+<a href="#Makefiles">Makefiles</a><br />
+<a href="#Testsuite">Testsuite Conventions</a><br />
+<a href="#Diagnostics">Diagnostics Conventions</a><br />
+<a href="#Spelling">Spelling, terminology and markup</a><br />
+<a href="#CandCxx">C and C++ Language Conventions</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#C_Options">Compiler Options</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#C_Language">Language Use</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Assertions">Assertions</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Character">Character Testing</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Error">Error Node Testing</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Generated">Parameters Affecting Generated Code</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#C_Inlining">Inlining Functions</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#C_Formatting">Formatting
Conventions</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Line">Line
Length</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#C_Names">Names</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Expressions">Expressions</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Calls">Function Calls</a><br />
+<a href="#Cxx_Conventions">C++ Language Conventions</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Cxx_Language">Language Use</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Variable">Variable Definitions</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Struct_Use">Struct Definitions</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Class_Use">Class Definitions</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Constructors">Constructors and Destructors</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Conversions">Conversions</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Over_Func">Overloading Functions</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Over_Oper">Overloading Operators</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Default">Default Arguments</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Cxx_Inlining">Inlining Functions</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Template_Use">Templates</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Namespace_Use">Namespaces</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#RTTI">RTTI
and <code>dynamic_cast</code></a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Casts">Other Casts</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Exceptions">Exceptions</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Standard_Library">The Standard Library</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Cxx_Formatting">Formatting
Conventions</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Cxx_Names">Names</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Struct_Form">Struct Definitions</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Class_Form">Class Definitions</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Member_Form">Class Member Definitions</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Template_Form">Templates</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#ExternC">Extern "C"</a><br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a
href="#Namespace_Form">Namespaces</a><br />
+</p>

-<h2>Documentation</h2>
+
+<h2><a name="Documentation">Documentation</a></h2>

 <p>Documentation, both of user interfaces and of internals, must be
 maintained and kept up to date.  In particular:</p>
@@ -43,7 +95,7 @@ 
 </ul>


-<h2>ChangeLogs</h2>
+<h2><a name="ChangeLogs">ChangeLogs</a></h2>

 <p>GCC requires ChangeLog entries for documentation changes; for the web
 pages (apart from <code>java/</code> and <code>libstdc++/</code>) the CVS
@@ -71,20 +123,61 @@ 
 <code>java/58</code> is the actual number of the PR) at the top
 of the ChangeLog entry.</p>

-<h2>Portability</h2>
+<h2><a name="Portability">Portability</a></h2>

 <p>There are strict requirements for portability of code in GCC to
-older systems whose compilers do not implement all of the ISO C standard.
-GCC requires at least an ANSI C89 or ISO C90 host compiler, and code
-should avoid pre-standard style function definitions, unnecessary
-function prototypes and use of the now deprecated @code{PARAMS} macro.
+older systems whose compilers do not implement all of the
+latest ISO C and C++ standards.
+</p>
+
+<p>
+The directories
+<code>gcc</code>, <code>libcpp</code> and <code>fixincludes</code>
+may use C++03.
+They may also use the <code>long long</code> type
+if the host C++ compiler supports it.
+Furthermore,
+these directories <em>should</em> also be compatible with C++11.
+</p>
+
+<p>
+The directories libiberty and libdecnumber must use C
+and require at least an ANSI C89 or ISO C90 host compiler.
+C code should avoid pre-standard style function definitions, unnecessary
+function prototypes and use of the now deprecated <code>PARAMS</code>
macro.
 See <a
href="http://gcc.gnu.org/cgi-bin/cvsweb.cgi/~checkout~/gcc/gcc/README.Portability?content-type=text/plain&amp;only_with_tag=HEAD">README.Portability</a>
 for details of some of the portability problems that may arise.  Some
 of these problems are warned about by <code>gcc -Wtraditional</code>,
 which is included in the default warning options in a bootstrap.
-(Code outside the C front end is only compiled by GCC, so such
-requirements do not apply to it.)</p>
+</p>
+
+<p>
+Every version of GCC must be buildable by the previous version of GCC.
+This rule helps ensure smooth development of the next version.
+However, it doesn't help so much when you do not have a previous version.
+So, the more important rule is that every version must bootstrap,
+which means that version can develop itself.
+Note that this statement does not preclude
+a need to build GCC with other compilers.
+</p>
+
+<p>
+We will periodically pick a stable version of GCC,
+and require that that version of GCC be able to build
+all versions of GCC up to and including the next stable version.
+E.g., we may decide that all newer versions of GCC
+should be buildable with GCC 4.3.5.
+</p>
+
+<p>
+It is desirable that it be possible to build GCC
+with C++ compilers other than GCC itself.
+If testing reveals that reasonably recent versions of non-GCC C++
compilers
+cannot compile GCC,
+then GCC code should be adjusted accordingly.
+(Avoiding unusual language constructs helps immensely.)
+</p>

 <p>The programs included in GCC are linked with the
 libiberty library, which will replace some standard
@@ -108,12 +201,6 @@ 
 the release cycle, to reduce the risk involved in fixing a problem
 that only shows up on one particular system.</p>

-<p>Avoid the use of identifiers or idioms that would prevent code
-compiling with a C++ compiler.  Identifiers such as <code>new</code>
-or <code>class</code>, that are reserved words in C++, should not be
-used as variables or field names.  Explicit casts should be used to
-convert between <code>void*</code> and other pointer types.</p>
-
 <p>Function prototypes for extern functions should only occur in
 header files.  Functions should be ordered within source files to
 minimize the number of function prototypes, by defining them before
@@ -121,13 +208,13 @@ 
 necessary, to break mutually recursive cycles.</p>


-<h2>Makefiles</h2>
+<h2><a name="Makefiles">Makefiles</a></h2>

 <p><code>touch</code> should never be used in GCC Makefiles.  Instead
 of <code>touch foo</code> always use <code>$(STAMP) foo</code>.</p>


-<h2>Testsuite Conventions</h2>
+<h2><a name="Testsuite">Testsuite Conventions</a></h2>

 <p>Every language or library feature, whether standard or a GNU
 extension, and every warning GCC can give, should have testcases
@@ -157,7 +244,7 @@ 
 to the test suite.</p>


-<h2>Diagnostics Conventions</h2>
+<h2><a name="Diagnostics">Diagnostics Conventions</a></h2>
 <ul>

 <li>Use of the <code>input_location</code> global, and of the
@@ -208,66 +295,7 @@ 
 </ul>


-<h2>Miscellaneous Conventions</h2>
-
-<p>Code should use <code>gcc_assert(EXPR)</code> to check invariants.
-Use <code>gcc_unreachable()</code> to mark places that should never be
-reachable (such as an unreachable <code>default</code> case of a
-switch).  Do not use <code>gcc_assert(0)</code> for such purposes, as
-<code>gcc_unreachable</code> gives the compiler more information.  The
-assertions are enabled unless explicitly configured off with
-<code>--enable-checking=none</code>.  Do not use <code>abort</code>.
-User input should never be validated by either <code>gcc_assert</code>
-or <code>gcc_unreachable</code>.  If the checks are expensive or the
-compiler can reasonably carry on after the error, they may be
-conditioned on <code>--enable-checking</code>.</p>
-
-<p>Code testing properties of characters from user source code should
-use macros such as <code>ISALPHA</code> from <code>safe-ctype.h</code>
-instead of the standard functions such as <code>isalpha</code> from
-<code>&lt;ctype.h&gt;</code> to avoid any locale-dependency of the
-language accepted.</p>
-
-<p>Code in GCC should use the following formatting conventions:</p>
-
-<table cellpadding="4">
-<tr>
-  <th align="right">Use...</th><th align="left">...instead of</th>
-</tr><tr>
-  <td align="right"><code>!x</code></td><td><code>! x</code></td>
-</tr><tr>
-  <td align="right"><code>~x</code></td><td><code>~ x</code></td>
-</tr><tr>
-  <td align="right"><code>-x</code> (unary minus)</td><td><code>-
x</code></td>
-</tr><tr>
-  <td align="right"><code>(foo) x</code> (cast)</td>
-  <td><code>(foo)x</code></td>
-</tr><tr>
-  <td align="right"><code>*x</code> (pointer dereference)</td>
-  <td><code>* x</code></td>
-</tr>
-</table>
-
-
-<p>Macros names should be in <code>ALL_CAPS</code> when it's important
-to be aware that it's a macro (e.g. accessors and simple predicates),
-but in lowercase (e.g., <code>size_int</code>) where the macro is a
-wrapper for efficiency that should be considered as a function; see
-messages <a
-href="http://gcc.gnu.org/ml/gcc-patches/2000-09/msg00901.html">1</a>
-and <a
-href="http://gcc.gnu.org/ml/gcc-patches/2000-09/msg00912.html">2</a>.</p>
-
-<p>Testing for <code>ERROR_MARK</code>s should be done by comparing
-against <code>error_mark_node</code> rather than by comparing the
-<code>TREE_CODE</code> against <code>ERROR_MARK</code>; see <a
-href="http://gcc.gnu.org/ml/gcc-patches/2000-10/msg00792.html">message</a>.</p>
-
-<p>Internal numeric parameters that may affect generated code should
-be controlled by <code>--param</code> rather than being hardcoded.</p>
-
-
-<h2>Spelling, terminology and markup</h2>
+<h2><a name="Spelling">Spelling, terminology and markup</a></h2>

 <p>The following conventions of spelling and terminology apply
 throughout GCC, including the manuals, web pages, diagnostics,
@@ -645,5 +673,682 @@ 

 </ul>

+
+<h2><a name="CandCxx">C and C++ Language Conventions</a></h2>
+
+<p>
+The following conventions apply to both C and C++.
+</p>
+
+
+<h3><a name="C_Options">Compiler Options</a></h3>
+
+<p>
+The compiler must build cleanly with <code>-Wall -Wextra</code>.
+</p>
+
+
+<h3><a name="C_Language">Language Use</a></h3>
+
+
+<h4><a name="Assertions">Assertions</a></h4>
+
+<p>Code should use <code>gcc_assert(EXPR)</code> to check invariants.
+Use <code>gcc_unreachable()</code> to mark places that should never be
+reachable (such as an unreachable <code>default</code> case of a
+switch).  Do not use <code>gcc_assert(0)</code> for such purposes, as
+<code>gcc_unreachable</code> gives the compiler more information.  The
+assertions are enabled unless explicitly configured off with
+<code>--enable-checking=none</code>.  Do not use <code>abort</code>.
+User input should never be validated by either <code>gcc_assert</code>
+or <code>gcc_unreachable</code>.  If the checks are expensive or the
+compiler can reasonably carry on after the error, they may be
+conditioned on <code>--enable-checking</code>.</p>
+
+
+<h4><a name="Character">Character Testing</a></h4>
+
+<p>Code testing properties of characters from user source code should
+use macros such as <code>ISALPHA</code> from <code>safe-ctype.h</code>
+instead of the standard functions such as <code>isalpha</code> from
+<code>&lt;ctype.h&gt;</code> to avoid any locale-dependency of the
+language accepted.</p>
+
+
+<h4><a name="Error">Error Node Testing</a></h4>
+
+<p>Testing for <code>ERROR_MARK</code>s should be done by comparing
+against <code>error_mark_node</code> rather than by comparing the
+<code>TREE_CODE</code> against <code>ERROR_MARK</code>; see <a
+href="http://gcc.gnu.org/ml/gcc-patches/2000-10/msg00792.html">message</a>.</p>
+
+
+<h4><a name="Generated">Parameters Affecting Generated Code</a></h4>
+
+<p>Internal numeric parameters that may affect generated code should
+be controlled by <code>--param</code> rather than being hardcoded.</p>
+
+
+<h4><a name="C_Inlining">Inlining Functions</a></h4>
+
+<p>
+Inlining functions only when
+you have reason to believe that
+the expansion of the function is smaller than a call to the function
+or that inlining is significant to the run-time of the compiler.
+</p>
+
+
+<h3><a name="C_Formatting">Formatting Conventions</a></h3>
+
+
+<h4><a name="Line">Line Length</a></h4>
+
+<p>Lines shall be at most 80 columns.</p>
+
+
+<h4><a name="C_Names">Names</a></h4>
+
+<p>
+Macros names should be in <code>ALL_CAPS</code>
+when it's important to be aware that it's a macro
+(e.g. accessors and simple predicates),
+but in lowercase (e.g., <code>size_int</code>)
+where the macro is a wrapper for efficiency
+that should be considered as a function;
+see messages
+<a href="http://gcc.gnu.org/ml/gcc-patches/2000-09/msg00901.html">1</a>
+and <a
href="http://gcc.gnu.org/ml/gcc-patches/2000-09/msg00912.html">2</a>.
+</p>
+
+<p>
+Other names should be lower-case and separated by low_lines.
+</p>
+
+
+<h4><a name="Expressions">Expressions</a></h4>
+
+<p>
+Code in GCC should use the following formatting conventions:
+</p>
+
+<table cellpadding="4">
+<tr>
+  <th align="left">For</th>
+  <th align="right">Use...</th><th align="left">...instead of</th>
+</tr><tr>
+  <td align="left">logical not</td>
+  <td align="right"><code>!x</code></td><td><code>! x</code></td>
+</tr><tr>
+  <td align="left">bitwise complement</td>
+  <td align="right"><code>~x</code></td><td><code>~ x</code></td>
+</tr><tr>
+  <td align="left">unary minus</td>
+  <td align="right"><code>-x</code></td><td><code>- x</code></td>
+</tr><tr>
+  <td align="left">cast</td>
+  <td align="right"><code>(foo) x</code></td>
+  <td><code>(foo)x</code></td>
+</tr><tr>
+  <td align="left">pointer dereference</td>
+  <td align="right"><code>*x</code></td>
+  <td><code>* x</code></td>
+</tr>
+</table>
+
+
+<h4><a name="Calls">Function Calls</a></h4>
+
+<p>
+All current GCC code uses a space between the function name
+and the left parenthesis in a function call.
+Essentially all C++ code omits that space,
+which is more consistent with C++ syntax.
+For the present we will retain the space.
+It is possible that in the future we will switch the code with a flag day.
+</p>
+
+
+<h2><a name="Cxx_Conventions">C++ Language Conventions</a></h2>
+
+<p>
+The following conventions apply only to C++.
+</p>
+
+<p>
+These conventions will change over time,
+but changing them requires that a convincing rationale.
+</p>
+
+
+<h3><a name="Cxx_Language">Language Use</a></h3>
+
+<p>
+C++ is a complex language,
+and we strive to use it in a manner that is not surprising.
+So, the primary rule is to be reasonable.
+Use a language feature in known good ways.
+If you need to use a feature in an unusual way,
+or a way that violates the "should" rules below,
+seek guidance, review and feedback from the wider community.
+</p>
+
+<p>
+All use of C++ features
+is subject to the decisions of the maintainers of the relevant components.
+(This restates something that is always true for gcc,
+which is that
+component maintainers make the final decisions about those components.)
+</p>
+
+<h4><a name="Variable">Variable Definitions</a></h4>
+
+<p>
+Variables should be defined at the point of first use,
+rather than at the top of the function.
+The existing code obviously does not follow that rule,
+so variables may be defined at the top of the function,
+as in C90.
+</p>
+
+<p>
+Variables may be simultaneously defined and tested in control expressions.
+</p>
+
+<p>
+<a href="codingrationale.html#variables">Rationale and Discussion</a>
+</p>
+
+
+<h4><a name="Struct_Use">Struct Definitions</a></h4>
+
+<p>
+Use the <code>struct</code> keyword for
+<a href="http://en.wikipedia.org/wiki/Plain_old_data_structure">
+plain old data (POD)</a> types.
+</p>
+
+<p>
+<a href="codingrationale.html#struct">Rationale and Discussion</a>
+</p>
+
+<h4><a name="Class_Use">Class Definitions</a></h4>
+
+<p>
+Use the <code>class</code> keyword for
+<a href="http://en.wikipedia.org/wiki/Plain_old_data_structure">
+non-POD</a> types.
+</p>
+
+<p>
+A non-POD type will often (but not always)
+have a declaration of a
+<a href="http://en.wikipedia.org/wiki/Special_member_functions">
+special member function</a>.
+If any one of these is declared,
+then all should be either declared
+or have an explicit comment saying that the default is intended.
+</p>
+
+<p>
+Single inheritance is permitted.
+Use public inheritance to describe interface inheritance,
+i.e. 'is-a' relationships.
+Use private and protected inheritance
+to describe implementation inheritance.
+Implementation inheritance can be expediant,
+but think twice before using it in code
+intended to last a long time.
+</p>
+
+<p>
+You should not use multiple inheritance.
+</p>
+
+<p>
+Think carefully about the size and performance impact
+of virtual functions and virtual bases
+before using them.
+</p>
+
+<p>
+Prefer to make data members private.
+</p>
+
+<p>
+<a href="codingrationale.html#class">Rationale and Discussion</a>
+</p>
+
+
+<h4><a name="Constructors">Constructors and Destructors</a></h4>
+
+<p>
+All constructors should initialize data members
+in the member initializer list rather than in the body of the constructor.
+</p>
+
+<p>
+A class with virtual functions or virtual bases
+should have a virtual destructor.
+</p>
+
+<p>
+<a href="codingrationale.html#constructors">Rationale and Discussion</a>
+</p>
+
+<h4><a name="Conversions">Conversions</a></h4>
+
+<p>
+Single argument constructors should nearly always be declared explicit.
+</p>
+
+<p>
+Conversion operators should be avoided.
+</p>
+
+<p>
+<a href="codingrationale.html#conversions">Rationale and Discussion</a>
+</p>
+
+
+<h4><a name="Over_Func">Overloading Functions</a></h4>
+
+<p>
+Overloading functions is permitted,
+but take care to ensure that overloads are not surprising,
+i.e. semantically identical or at least very similar.
+Virtual functions should not be overloaded.
+</p>
+
+<p>
+<a href="codingrationale.html#overfunc">Rationale and Discussion</a>
+</p>
+
+
+<h4><a name="Over_Oper">Overloading Operators</a></h4>
+
+<p>
+Overloading operators is permitted,
+but take care to ensure that overloads are not surprising.
+Some unsurprising uses are
+in the implementation of numeric types and
+in following the C++ Standard Library's conventions.
+In addition, overloaded operators, excepting the call operator,
+should not be used for expensive implementations.
+</p>
+
+<p>
+<a href="codingrationale.html#overoper">Rationale and Discussion</a>
+</p>
+
+
+<h4><a name="Default">Default Arguments</a></h4>
+
+<p>
+Default arguments are another type of function overloading,
+and the same rules apply.
+Default arguments must always be POD values, i.e. may not run
constructors.
+Virtual functions should not have default arguments.
+</p>
+
+<p>
+<a href="codingrationale.html#default">Rationale and Discussion</a>
+</p>
+
+
+<h4><a name="Cxx_Inlining">Inlining Functions</a></h4>
+
+<p>
+Constructors and destructors, even those with empty bodies,
+are often much larger than programmers expect.
+Prefer non-inline versions unless you have evidence
+that the inline version is smaller or has a significant performance
impact.
+</p>
+
+
+<h4><a name="Template_Use">Templates</a></h4>
+
+<p>
+To avoid excessive compiler size,
+consider implementing non-trivial templates
+on a non-template base class with <code>void*</code> parameters.
+</p>
+
+
+<h4><a name="Namespace_Use">Namespaces</a></h4>
+
+<p>
+Namespaces are encouraged.
+All separable libraries should have a unique global namespace.
+All individual tools should have a unique global namespace.
+Nested include directories names should map to nested namespaces when
possible.
+</p>
+
+<p>
+Header files should have neither <code>using</code> directives
+nor namespace-scope <code>using</code> declarations.
+</p>
+
+<p>
+There is no alternative to <code>using</code> declarations
+in class definitions to manage names within an inheritance hierarchy,
+so they are necessarily permitted.
+</p>
+
+<p>
+<a href="codingrationale.html#namespaces">Rationale and Discussion</a>
+</p>
+
+<h4><a name="RTTI">RTTI and <code>dynamic_cast</code></a></h4>
+
+<p>
+Run-time type information (RTTI) is permitted
+when certain non-default <code>--enable-checking</code> options are
enabled,
+so as to allow checkers to report dynamic types.
+However, by default, RTTI is not permitted
+and the compiler must build cleanly with <code>-fno-rtti</code>.
+</p>
+
+<p>
+<a href="codingrationale.html#RTTI">Rationale and Discussion</a>
+</p>
+
+
+<h4><a name="Casts">Other Casts</a></h4>
+
+<p>
+C-style casts should not be used.
+Instead, use C++-style casts.
+</p>
+
+<p>
+<a href="codingrationale.html#casts">Rationale and Discussion</a>
+</p>
+
+
+<h4><a name="Exceptions">Exceptions</a></h4>
+
+<p>
+Exceptions and throw specifications are not permitted
+and the compiler must build cleanly with <code>-fno-exceptions</code>.
+</p>
+
+<p>
+<a href="codingrationale.html#exceptions">Rationale and Discussion</a>
+</p>
+
+
+<h4><a name="Standard_Library">The Standard Library</a></h4>
+
+<p>
+Use of the standard library is permitted.
+Note, however, that it is currently not usable with garbage collected
data.
+</p>
+
+<p>
+For compiler messages, indeed any text that needs i18n,
+should continue to use the existing facilities.
+</p>
+
+<p>
+For long-term code, at least for now,
+we will continue to use <code>printf</code> style I/O
+rather than <code>&lt;iostream&gt;</code> style I/O.
+For quick debugging code,
+<code>&lt;iostream&gt;</code> is permitted.
+</p>
+
+<p>
+<a href="codingrationale.html#stdlib">Rationale and Discussion</a>
+</p>
+
+
+<h3><a name="Cxx_Formatting">Formatting Conventions</a></h3>
+
+
+<h4><a name="Cxx_Names">Names</a></h4>
+
+<p>
+When structs and/or classes have member functions,
+prefer to name data members with a trailing underscore.
+</p>
+
+<p>
+Template parameter names should use CamelCase,
+following the C++ Standard.
+</p>
+
+<p>
+<a href="codingrationale.html#stdlib">Rationale and Discussion</a>
+</p>
+
+
+<h4><a name="Struct_Form">Struct Definitions</a></h4>
+
+<p>
+Note that the rules for classes do not apply to structs.
+Structs continue to behave as before.
+</p>
+
+
+<h4><a name="Class_Form">Class Definitions</a></h4>
+
+<p>
+If the entire class definition fits on a single line, put it on a single
line.
+Otherwise, use the following rules.
+</p>
+
+<p>
+Indent protection labels by one space.
+</p>
+
+<p>
+Indent class members by two spaces.
+</p>
+
+<p>
+Prefer to put the entire class head on a single line.
+</p>
+
+<blockquote><pre><code>
+class gnuclass : base {
+</code></pre></blockquote>
+
+<p>
+Otherwise, start the colon of the base list at the beginning of a line.
+</p>
+
+<blockquote><pre><code>
+class a_rather_long_class_name
+: with_a_very_long_base_name, and_another_just_to_make_life_hard
+{
+  int member;
+};
+</code></pre></blockquote>
+
+<p>
+If the base clause exceeds one line,
+move overflowing initializers to the next line and indent by two spaces.
+</p>
+
+<blockquote><pre><code>
+class gnuclass
+: base1 &lt;template_argument1&gt;, base2 &lt;template_argument1&gt;,
+  base3 &lt;template_argument1&gt;, base4 &lt;template_argument1&gt;
+{
+  int member;
+};
+</code></pre></blockquote>
+
+<p>
+When defining a class,
+</p>
+<ul>
+<li>first define all public types,</li>
+<li>then define all non-public types,</li>
+<li>then declare all public constructors,</li>
+<li>then declare the public destructor,</li>
+<li>then declare all public member functions,</li>
+<li>then declare all public member variables,</li>
+<li>then declare all non-public constructors,</li>
+<li>then declare the non-public destructor,</li>
+<li>then declare all non-public member functions, and</li>
+<li>then declare all non-public member variables.</li>
+</ul>
+
+<p>
+Semantic constraints may require a different declaration order,
+but seek to minimize the potential confusion.
+</p>
+
+<p>
+Close a class definition
+with a right brace, semicolon, optional closing comment, and a new line.
+</p>
+
+<blockquote><pre><code>
+} // class gnuclass
+</code></pre></blockquote>
+
+
+<h4><a name="Member_Form">Class Member Definitions</a></h4>
+
+<p>
+Define all members outside the class definition.
+That is, there are no function bodies or member initializers
+inside the class definition.
+</p>
+
+<p>
+Prefer to put the entire member head on a single line.
+</p>
+
+<blockquote><pre><code>
+gnuclass::gnuclass() : base_class()
+{
+  ...
+};
+</code></pre></blockquote>
+
+<p>
+When that is not possible,
+place the colon of the initializer clause at the beginning of a line.
+</p>
+
+<blockquote><pre><code>
+gnuclass::gnuclass()
+: base1(), base2(), member1(), member2(), member3(), member4()
+{
+  ...
+};
+</code></pre></blockquote>
+
+<p>
+If the initializer clause exceeds one line,
+move overflowing initializers to the next line and indent by two spaces.
+</p>
+
+<blockquote><pre><code>
+gnuclass::gnuclass()
+: base1(some_expression), base2(another_expression),
+  member1(my_expressions_everywhere)
+{
+  ...
+};
+</code></pre></blockquote>
+
+<p>
+If a C++ function name is long enough
+to cause the first function parameter with its type to exceed 80
characters,
+it should appear on the next line indented four spaces.
+</p>
+
+<blockquote><pre><code>
+void
+very_long_class_name::very_long_function_name(
+    very_long_type_name arg)
+{
+</code></pre></blockquote>
+
+<p>
+Sometimes the class qualifier and function name together exceed 80
characters.
+In this case, break the line before the <code>::</code> operator.
+We may wish to do so pre-emptively for all class member functions.
+</p>
+
+<blockquote><pre><code>
+void
+very_long_template_class_name &lt;with, a, great, many, arguments&gt;
+::very_long_function_name(
+    very_long_type_name arg)
+{
+</code></pre></blockquote>
+
+
+<h4><a name="Template_Form">Templates</a></h4>
+
+<p>
+A declaration following a template parameter list
+should not have additional indentation.
+</p>
+
+<p>
+Prefer <code>typename</code> over <code>class</code>
+in template parameter lists.
+</p>
+
+
+<h4><a name="ExternC">Extern "C"</a></h4>
+
+<p>
+Prefer an <code>extern "C"</code> block to a declaration qualifier.
+</p>
+
+<p>
+Open an <code>extern "C"</code> block with the left brace on the same
line.
+</p>
+
+<blockquote><pre><code>
+extern "C" {
+</code></pre></blockquote>
+
+<p>
+Close an <code>extern "C"</code> block
+with a right brace, optional closing comment, and a new line.
+</p>
+
+<blockquote><pre><code>
+} // extern "C"
+</code></pre></blockquote>
+
+<p>
+Definitions within the body of a namespace are not indented.
+</p>
+
+<h4><a name="Namespace_Form">Namespaces</a></h4>
+
+<p>
+Open a namespace with the namespace name
+followed by a left brace and a new line.
+</p>
+
+<blockquote><pre><code>
+namespace gnutool {
+</code></pre></blockquote>
+
+<p>
+Close a namespace
+with a right brace, optional closing comment, and a new line.
+</p>
+
+<blockquote><pre><code>
+} // namespace gnutool
+</code></pre></blockquote>
+
+<p>
+Definitions within the body of a namespace are not indented.
+</p>
+
+
 </body>
 </html>
Index: codingrationale.html
===================================================================
RCS file: codingrationale.html
diff -N codingrationale.html
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ codingrationale.html	18 Jun 2012 22:04:49 -0000
@@ -0,0 +1,386 @@ 
+
+<head>
+<title>GCC Coding Conventions Rationale and Discussion</title>
+</head>
+
+<body>
+<h1>GCC Coding Conventions Rationale and Discussion</h1>
+
+<h2>C and C++ Language Conventions</h2>
+
+<h3>Language Use</h3>
+
+<h4>Inlining Functions</h4>
+
+<p>
+Inlining functions has a potential cost in object size,
+working set size, compile time, and debuggablity.
+These costs should not be borne without some evidence
+that the inlining pays for itself.
+</p>
+
+
+<h2>C++ Language Conventions</h2>
+
+<h3>Language Use</h3>
+
+<h4><a name="variables">Variable Definitions</a></h4>
+
+<p>
+Defining variables when they are first needed
+reduces the cognitive burden on the programmer.
+It also eases converting common sub-expressions
+into a defined and reused variable.
+</p>
+
+<p>
+Defining and testing variables in control expressions
+has the same advantages as above.
+In addition, it restricts the scope of the variable
+to the region in which it is known to be sensible.
+</p>
+
+<blockquote><pre><code>
+if (info *q = get_any_available_info ()) {
+  // q is known to be non-NULL, and so do useful processing.
+}
+</code></pre></blockquote>
+
+
+<h4><a name="struct">Struct Definitions</a></h4>
+
+<p>
+In the C++ standard,
+structs and classes differ only in the default access rules.
+We prefer to use these two keywords to signal more information.
+</p>
+
+<p>
+Note that under this definition,
+structs may have member functions.
+This freedom is useful for transitional code.
+</p>
+
+
+<h4><a name="class">Class Definitions</a></h4>
+
+<p>
+Forgetting to write a special member function is a known programming
problem.
+Some authors recommend always defining all special member functions.
+Such classes are less efficient.
+First, these definitions may prevent the compiler
+from passing the class in a register.
+Second, these definitions may prevent the compiler
+from using more efficient methods for copying.
+Adding a comment that the default is intended
+preserves the performance while ensuring that
+the function was not forgotten.
+</p>
+
+<p>
+FIXME: Discussion of deleting inappropraite special members.
+Classes generally are either value classes or identity classes.
+Copy constructors and assignment operators are fine for value classes.
+They are often not appropriate to identity classes.
+These classes should delete, or disable, these functions.
+Marking such functions as follows
+will enable compiling against C++03,
+and later modifying them for C++11.
+</p>
+
+<blockquote><pre><code>
+TypeName(const TypeName&amp;) /*DELETED*/;
+void operator=(const TypeName&amp;) /*DELETED*/;
+</code></pre></blockquote>
+
+<p>
+Multiple inheritance is confusing and rarely useful.
+When it is needed though, there may be no substitute.
+Seek guidance, review and feedback from the wider community.
+</p>
+
+<p>
+Using virtual functions increases the size of instances of the class
+by at least one pointer.
+In heavily allocated types, such as trees, GIMPLE or RTL,
+this size increase could have adverse performance impacts.
+On the other hand,
+virtual functions can often reduce the size of instances
+by binding information into the virtual tables and the virtual functions.
+For example, various type tags need not be present.
+Other attributes can be inferred
+from type and more general information,
+or from extending the class hierarchy at the leaves.
+So, even though trees are heavily allocated,
+it remains to be seen whether virtual functions would increase the size.
+Therefore virtual functions should be added in heavily allocated classes
+only after size and performance studies.
+However, virtual functions are acceptable where we use hooks today,
+as they are already essentially virtual tables.
+</p>
+
+<p>
+There are good reasons to make private
+all data members of non-POD classes.
+However, in converting from C to C++,
+there is a necessary transition that has public data members.
+</p>
+
+
+<h4><a name="constructors">Constructors and Destructors</a></h4>
+
+<p>
+The compiler implicitly initializes all non-POD fields.
+Any initialization in the body of the constructor implies extra work.
+</p>
+
+<p>
+Polymorphic classes without a virtual destructor
+are almost certainly incorrect.
+</p>
+
+<h4><a name="conversions">Conversions</a></h4>
+
+<p>
+C++ uses single-argument constructors for implicit type conversion.
+Wide use of implicit conversion can cause some very surprising results.
+</p>
+
+<p>
+C++03 has no explicit conversion operators,
+and hence using them cannot avoid suprises.
+Wait for C++11.
+</p>
+
+
+<h4><a name="overfunc">Overloading Functions</a></h4>
+
+<p>
+Function overloading can be confusing.
+However, in some cases introducing new function names adds little value,
+as in the current distinction
+between <code>build_index_type</code> and <code>build_index_2_type</code>.
+</p>
+
+<p>
+The essential problem is to use overloading in a way that
+improves conciseness without introducing confusion.
+To that end, consider the following advice.
+</p>
+
+<p>
+You may overload if the overloaded name supports an action notion.
+For example, the C++ standard's notion of swap.
+</p>
+
+<p>
+You may <em>not</em> overload
+when implicit conversions among argument types may yield unintended
effects.
+For example,
+</p>
+
+<blockquote><pre><code>
+void swizzle (int arg);
+void swizzle (const char *arg);
+... swizzle (NULL); ...
+</code></pre></blockquote>
+
+<p>
+results in an unintended call to the <code>int</code> overload on some
systems.
+In practice, the problem that this restriction addresses
+arises more from bad user-defined implicit conversion operators.
+See ISO C++
+<a
href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2437.pdf">
+N2437</a>
+and
+ISO C++
+<a
href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2514.html">
+N2514</a>.
+</p>
+
+<p>
+You may overload if a single argument, in a single position,
+has multiple representations. For example,
+</p>
+
+<blockquote><pre><code>
+void append (const char *str);
+void append (std::string str);
+</code></pre></blockquote>
+
+<p>
+You may <em>not</em> overload
+if more than one argument constitutes the representation of some data
notion.
+For example, in
+</p>
+
+<blockquote><pre><code>
+void register (int house, const char *street, int zipcode);
+</code></pre></blockquote>
+
+<p>
+the arguments are a representation of addresses.
+Instead, the overload should be on addresses.
+</p>
+
+<blockquote><pre><code>
+void register(const Address &amp;addr);
+</code></pre></blockquote>
+
+<p>
+This restriction cannot apply to constructors,
+where the whole point is to collect representational data.
+</p>
+
+<blockquote><pre><code>
+Address::Address (int house, const char *street, int zipcode);
+</code></pre></blockquote>
+
+<p>
+Notwithstanding the restrictions above, you may overload to detect errors.
+That is, if unsigned numbers are good, but signed numbers are bad,
+you could overload
+</p>
+
+<blockquote><pre><code>
+void munch (unsigned int arg);
+void munch (int arg);
+</code></pre></blockquote>
+
+<p>
+and simply not define the signed int version.
+Anyone using it would get a link-time error.
+(The C++11 standard has a syntax
+that enables compile-time detection of the problem.)
+</p>
+
+
+<h4><a name="overoper">Overloading Operators</a></h4>
+
+<p>
+Using <code>[]</code> to index a vector is unsurprising,
+but using <code>[]</code> to query a database over a network
+is bound to cause performance problems.
+</p>
+
+
+<h4><a name="default">Default Arguments</a></h4>
+
+<p>
+Expensive default arguments can cause hard-to-identify performance
problems.
+</p>
+
+<p>
+Default arguments cause confusion
+when attempting to take the address of a function.
+They clause client code taking the address of a function
+to break when a default argument is replaced by a specialized overload.
+So, default arguments should generally not be used
+in customer-facing interfaces.
+Consider function overloading instead.
+</p>
+
+
+<h4><a name="namespace">Namespaces</a></h4>
+
+<p>
+Putting <code>using</code> directives
+or namespace-scope <code>using</code> declarations
+into header files can change client code in surprising ways.
+</p>
+
+<p>
+Using them within an implementation file can help conciseness.
+</p>
+
+
+<h4><a name="RTTI">RTTI and <code>dynamic_cast</code></a></h4>
+
+<p>
+Disabling RTTI will save space in the compiler.
+</p>
+
+<p>
+Checking the type of a class at runtime usually indicates a design
problem.
+If you need classes to behave differently at runtime, use a virtual
method.
+If you need to know the type of a class for some other reason,
+use an enum or a virtual member function
+that coverts a pointer to the more derived class.
+For example,
+</p>
+
+<blockquote><pre><code>
+common_type *p = ....;
+if (specific_type *q = p-&gt;to_specific ()) {
+  // We have and can use a specific_type pointed to by q.
+}
+</code></pre></blockquote>
+
+<h4><a name="casts">Other Casts</a></h4>
+
+<p>
+C++-style casts are very explicit in the intended transformation.
+Making intent clear avoids bugs and helps with other programmers.
+</p>
+
+
+<h4><a name="exceptions">Exceptions</a></h4>
+
+<p>
+The current compiler code is not exception safe.
+</p>
+
+<p>
+Disabling exceptions will permit
+the compiler itself to be slightly more optimized.
+</p>
+
+<p>
+Aborting the compiler is a reasonable response to unexpected problems.
+</p>
+
+<p>
+We would like the compiler to be exception safe,
+to permit reconsideration of the exception convention.
+This change would require a significant change in style,
+adopting "resource acquisition is initialization" (RAII).
+We would be using
+<code>shared_ptr</code> (from TR1's <code>&lt;memory&gt;</code>)
+or <code>unique_ptr</code> (from C++11).
+</p>
+
+<h4><a name="stdlib">The Standard Library</a></h4>
+
+<p>
+At present, C++ provides no great advantage for i18n.
+GCC does type checking for <code>printf</code> arguments,
+so the type insecurity of <code>printf</code> is moot,
+but the clarity in layout persists.
+For quick debugging output, &lt;iostream&gt; requires less work.
+</p>
+
+<h3>Formatting Conventions</h3>
+
+<h4><a href="names">Names</a></h4>
+
+<p>
+Naming data members with a trailing underscore
+highlights the extra overhead of access to fields over local variables.
+Think of the trailing underscore
+like you would Pascal's postfix <code>^</code> dereference operator.
+</p>
+
+<p>
+When using the above convention,
+the constructor parameter names
+and getter member function names
+can use the more concise non-underscore form.