| Message ID | CAGqM8fbU2d7v_aG--LqGhmzi1dOGcHq030BdaSndR6yvT4Ud3A@mail.gmail.com |
|---|---|
| State | New |
| Headers | show |
[ 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 /> > + <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
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. > > + <a href="#C_Options">Compiler Options</a><br /> I don't like this repeated 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.
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. > > > + <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.
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
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
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 >
[...] | > 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
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><iostream></code> style I/O. > +For quick debugging code, > +<code><iostream></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.
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.
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><iostream></code> style I/O. >> +For quick debugging code, >> +<code><iostream></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.
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.).
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.