[ 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 <cr...@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 />
> + <a href="#C_Options">Compiler Options</a><br />
> + <a href="#C_Language">Language Use</a><br />
> + <a
> href="#Assertions">Assertions</a><br />
> + <a
> href="#Character">Character Testing</a><br />
> + <a
> href="#Error">Error Node Testing</a><br />
> + <a
> href="#Generated">Parameters Affecting Generated Code</a><br />
> + <a
> href="#C_Inlining">Inlining Functions</a><br />
> + <a href="#C_Formatting">Formatting
> Conventions</a><br />
> + <a href="#Line">Line
> Length</a><br />
> + <a
> href="#C_Names">Names</a><br />
> + <a
> href="#Expressions">Expressions</a><br />
> + <a
> href="#Calls">Function Calls</a><br />
> +<a href="#Cxx_Conventions">C++ Language Conventions</a><br />
> + <a href="#Cxx_Language">Language Use</a><br />
> + <a
> href="#Variable">Variable Definitions</a><br />
> + <a
> href="#Struct_Use">Struct Definitions</a><br />
> + <a
> href="#Class_Use">Class Definitions</a><br />
> + <a
> href="#Constructors">Constructors and Destructors</a><br />
> + <a
> href="#Conversions">Conversions</a><br />
> + <a
> href="#Over_Func">Overloading Functions</a><br />
> + <a
> href="#Over_Oper">Overloading Operators</a><br />
> + <a
> href="#Default">Default Arguments</a><br />
> + <a
> href="#Cxx_Inlining">Inlining Functions</a><br />
> + <a
> href="#Template_Use">Templates</a><br />
> + <a
> href="#Namespace_Use">Namespaces</a><br />
> + <a href="#RTTI">RTTI
> and <code>dynamic_cast</code></a><br />
> + <a
> href="#Casts">Other Casts</a><br />
> + <a
> href="#Exceptions">Exceptions</a><br />
> + <a
> href="#Standard_Library">The Standard Library</a><br />
> + <a href="#Cxx_Formatting">Formatting
> Conventions</a><br />
> + <a
> href="#Cxx_Names">Names</a><br />
> + <a
> href="#Struct_Form">Struct Definitions</a><br />
> + <a
> href="#Class_Form">Class Definitions</a><br />
> + <a
> href="#Member_Form">Class Member Definitions</a><br />
> + <a
> href="#Template_Form">Templates</a><br />
> + <a
> href="#ExternC">Extern "C"</a><br />
> + <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&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><ctype.h></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><ctype.h></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><iostream></code> style I/O.
> +For quick debugging code,
> +<code><iostream></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 <template_argument1>, base2 <template_argument1>,
> + base3 <template_argument1>, base4 <template_argument1>
> +{
> + 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 <with, a, great, many, arguments>
> +::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&) /*DELETED*/;
> +void operator=(const TypeName&) /*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 &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->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><memory></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, <iostream> 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
