On 6/25/12, Lawrence Crowl <cr...@google.com> wrote:
> On 6/25/12, Joseph S. Myers <jos...@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.
>
>> > > + <a href="#C_Options">Compiler Options</a><br
>> > > />
>>
>> I don't like this repeated 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.
>
> --
> Lawrence Crowl
Sorry, I forgot to add the patch. Note that I have removed some
html headers that cause gcc mail grief.
Index: htdocs/codingconventions.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/codingconventions.html,v
retrieving revision 1.66
diff -u -u -r1.66 codingconventions.html
--- htdocs/codingconventions.html 19 Feb 2012 00:45:34 -0000 1.66
+++ htdocs/codingconventions.html 25 Jun 2012 22:19:46 -0000
@@ -15,8 +19,71 @@
code to follow these conventions, it is best to send changes to follow
the conventions separately from any other changes to the code.</p>
+<ul>
+<li><a href="#Documentation">Documentation</a></li>
+<li><a href="#ChangeLogs">ChangeLogs</a></li>
+<li><a href="#Portability">Portability</a></li>
+<li><a href="#Makefiles">Makefiles</a></li>
+<li><a href="#Testsuite">Testsuite Conventions</a></li>
+<li><a href="#Diagnostics">Diagnostics Conventions</a></li>
+<li><a href="#Spelling">Spelling, terminology and markup</a></li>
+<li><a href="#CandCxx">C and C++ Language Conventions</a>
+ <ul>
+ <li><a href="#C_Options">Compiler Options</a></li>
+ <li><a href="#C_Language">Language Use</a>
+ <ul>
+ <li><a href="#Assertions">Assertions</a></li>
+ <li><a href="#Character">Character Testing</a></li>
+ <li><a href="#Error">Error Node Testing</a></li>
+ <li><a href="#Generated">Parameters Affecting Generated Code</a></li>
+ <li><a href="#C_Inlining">Inlining Functions</a></li>
+ </ul>
+ </li>
+ <li><a href="#C_Formatting">Formatting Conventions</a>
+ <ul>
+ <li><a href="#Line">Line Length</a></li>
+ <li><a href="#C_Names">Names</a></li>
+ <li><a href="#Expressions">Expressions</a></li>
+ </ul>
+ </li>
+ </ul>
+</li>
+<li><a href="#Cxx_Conventions">C++ Language Conventions</a>
+ <ul>
+ <li><a href="#Cxx_Language">Language Use</a>
+ <ul>
+ <li><a href="#Variable">Variable Definitions</a></li>
+ <li><a href="#Struct_Use">Struct Definitions</a></li>
+ <li><a href="#Class_Use">Class Definitions</a></li>
+ <li><a href="#Constructors">Constructors and Destructors</a></li>
+ <li><a href="#Conversions">Conversions</a></li>
+ <li><a href="#Over_Func">Overloading Functions</a></li>
+ <li><a href="#Over_Oper">Overloading Operators</a></li>
+ <li><a href="#Default">Default Arguments</a></li>
+ <li><a href="#Cxx_Inlining">Inlining Functions</a></li>
+ <li><a href="#Template_Use">Templates</a></li>
+ <li><a href="#Namespace_Use">Namespaces</a></li>
+ <li><a href="#RTTI">RTTI and <code>dynamic_cast</code></a></li>
+ <li><a href="#Casts">Other Casts</a></li>
+ <li><a href="#Exceptions">Exceptions</a></li>
+ <li><a href="#Standard_Library">The Standard Library</a></li>
+ </ul>
+ </li>
+ <li><a href="#Cxx_Formatting">Formatting Conventions</a></li>
+ <ul>
+ <li><a href="#Cxx_Names">Names</a></li>
+ <li><a href="#Struct_Form">Struct Definitions</a></li>
+ <li><a href="#Class_Form">Class Definitions</a></li>
+ <li><a href="#Member_Form">Class Member Definitions</a></li>
+ <li><a href="#Template_Form">Templates</a></li>
+ <li><a href="#ExternC">Extern "C"</a></li>
+ <li><a href="#Namespace_Form">Namespaces</a></li>
+ </ul>
+ </li>
+</ul>
-<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 +110,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 +138,40 @@
<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.
+These directories should use reasonably portable parts of C++03,
+so that it is 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.)
+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>The programs included in GCC are linked with the
libiberty library, which will replace some standard
@@ -108,12 +195,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 +202,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 +238,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 +289,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 +667,668 @@
</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>
+
+
+<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>
+Complex heirarchies are to be avoided.
+Take special care with multiple inheritance.
+On the rare occasion that using mulitple inheritance is indeed useful,
+prepare design rationales in advance,
+and take special care to make documentation of the entire hierarchy clear.
+</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>
+<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: htdocs/codingrationale.html
===================================================================
RCS file: htdocs/codingrationale.html
diff -N htdocs/codingrationale.html
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ htdocs/codingrationale.html 25 Jun 2012 22:19:46 -0000
@@ -0,0 +1,389 @@
+<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.
+Virtual functions are implemented as indirect function calls,
+which can inhibit some optimization,
+particularly inlining.
+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
