Index: htdocs/codingconventions.html =================================================================== RCS file: /cvs/gcc/wwwdocs/htdocs/codingconventions.html,v retrieving revision 1.66 diff -u -u -r1.66 codingconventions.html --- htdocs/codingconventions.html 19 Feb 2012 00:45:34 -0000 1.66 +++ htdocs/codingconventions.html 25 Jun 2012 22:19:46 -0000 @@ -15,8 +19,71 @@ code to follow these conventions, it is best to send changes to follow the conventions separately from any other changes to the code.
+Documentation, both of user interfaces and of internals, must be maintained and kept up to date. In particular:
@@ -43,7 +110,7 @@ -GCC requires ChangeLog entries for documentation changes; for the web
pages (apart from java/
and libstdc++/
) the CVS
@@ -71,20 +138,40 @@
java/58
is the actual number of the PR) at the top
of the ChangeLog entry.
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. +
+ +
+The directories
+gcc
, libcpp
and fixincludes
+may use C++03.
+They may also use the long long
type
+if the host C++ compiler supports it.
+These directories should use reasonably portable parts of C++03,
+so that it is possible to build GCC with C++ compilers other than GCC itself.
+If testing reveals that
+reasonably recent versions of non-GCC C++ compilers cannot compile GCC,
+then GCC code should be adjusted accordingly.
+(Avoiding unusual language constructs helps immensely.)
+Furthermore,
+these directories should also be compatible with C++11.
+
+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 PARAMS
macro.
See README.Portability
for details of some of the portability problems that may arise. Some
of these problems are warned about by gcc -Wtraditional
,
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.)
The programs included in GCC are linked with the libiberty library, which will replace some standard @@ -108,12 +195,6 @@ the release cycle, to reduce the risk involved in fixing a problem that only shows up on one particular system.
-Avoid the use of identifiers or idioms that would prevent code
-compiling with a C++ compiler. Identifiers such as new
-or class
, that are reserved words in C++, should not be
-used as variables or field names. Explicit casts should be used to
-convert between void*
and other pointer types.
Function prototypes for extern functions should only occur in header files. Functions should be ordered within source files to minimize the number of function prototypes, by defining them before @@ -121,13 +202,13 @@ necessary, to break mutually recursive cycles.
-touch
should never be used in GCC Makefiles. Instead
of touch foo
always use $(STAMP) foo
.
Every language or library feature, whether standard or a GNU extension, and every warning GCC can give, should have testcases @@ -157,7 +238,7 @@ to the test suite.
-input_location
global, and of the
@@ -208,66 +289,7 @@
Code should use gcc_assert(EXPR)
to check invariants.
-Use gcc_unreachable()
to mark places that should never be
-reachable (such as an unreachable default
case of a
-switch). Do not use gcc_assert(0)
for such purposes, as
-gcc_unreachable
gives the compiler more information. The
-assertions are enabled unless explicitly configured off with
---enable-checking=none
. Do not use abort
.
-User input should never be validated by either gcc_assert
-or gcc_unreachable
. If the checks are expensive or the
-compiler can reasonably carry on after the error, they may be
-conditioned on --enable-checking
.
Code testing properties of characters from user source code should
-use macros such as ISALPHA
from safe-ctype.h
-instead of the standard functions such as isalpha
from
-<ctype.h>
to avoid any locale-dependency of the
-language accepted.
Code in GCC should use the following formatting conventions:
- -Use... | ...instead of | -
---|---|
!x | ! x |
-
~x | ~ x |
-
-x (unary minus) | - x |
-
(foo) x (cast) |
- (foo)x |
-
*x (pointer dereference) |
- * x |
-
Macros names should be in ALL_CAPS
when it's important
-to be aware that it's a macro (e.g. accessors and simple predicates),
-but in lowercase (e.g., size_int
) where the macro is a
-wrapper for efficiency that should be considered as a function; see
-messages 1
-and 2.
Testing for ERROR_MARK
s should be done by comparing
-against error_mark_node
rather than by comparing the
-TREE_CODE
against ERROR_MARK
; see message.
Internal numeric parameters that may affect generated code should
-be controlled by --param
rather than being hardcoded.
The following conventions of spelling and terminology apply throughout GCC, including the manuals, web pages, diagnostics, @@ -645,5 +667,668 @@ + +
+The following conventions apply to both C and C++. +
+ + +
+The compiler must build cleanly with -Wall -Wextra
.
+
Code should use gcc_assert(EXPR)
to check invariants.
+Use gcc_unreachable()
to mark places that should never be
+reachable (such as an unreachable default
case of a
+switch). Do not use gcc_assert(0)
for such purposes, as
+gcc_unreachable
gives the compiler more information. The
+assertions are enabled unless explicitly configured off with
+--enable-checking=none
. Do not use abort
.
+User input should never be validated by either gcc_assert
+or gcc_unreachable
. If the checks are expensive or the
+compiler can reasonably carry on after the error, they may be
+conditioned on --enable-checking
.
Code testing properties of characters from user source code should
+use macros such as ISALPHA
from safe-ctype.h
+instead of the standard functions such as isalpha
from
+<ctype.h>
to avoid any locale-dependency of the
+language accepted.
Testing for ERROR_MARK
s should be done by comparing
+against error_mark_node
rather than by comparing the
+TREE_CODE
against ERROR_MARK
; see message.
Internal numeric parameters that may affect generated code should
+be controlled by --param
rather than being hardcoded.
+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. +
+ + +Lines shall be at most 80 columns.
+ + +
+Macros names should be in ALL_CAPS
+when it's important to be aware that it's a macro
+(e.g. accessors and simple predicates),
+but in lowercase (e.g., size_int
)
+where the macro is a wrapper for efficiency
+that should be considered as a function;
+see messages
+1
+and 2.
+
+Other names should be lower-case and separated by low_lines. +
+ + ++Code in GCC should use the following formatting conventions: +
+ +For | +Use... | ...instead of | +
---|---|---|
logical not | +!x | ! x |
+
bitwise complement | +~x | ~ x |
+
unary minus | +-x | - x |
+
cast | +(foo) x |
+ (foo)x |
+
pointer dereference | +*x |
+ * x |
+
+The following conventions apply only to C++. +
+ ++These conventions will change over time, +but changing them requires that a convincing rationale. +
+ + ++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. +
+ ++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.) +
+ ++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. +
+ ++Variables may be simultaneously defined and tested in control expressions. +
+ + + + +
+Use the struct
keyword for
+
+plain old data (POD) types.
+
+Use the class
keyword for
+
+non-POD types.
+
+A non-POD type will often (but not always) +have a declaration of a + +special member function. +If any one of these is declared, +then all should be either declared +or have an explicit comment saying that the default is intended. +
+ ++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. +
+ ++Complex heirarchies are to be avoided. +Take special care with multiple inheritance. +On the rare occasion that using mulitple inheritance is indeed useful, +prepare design rationales in advance, +and take special care to make documentation of the entire hierarchy clear. +
+ ++Think carefully about the size and performance impact +of virtual functions and virtual bases +before using them. +
+ ++Prefer to make data members private. +
+ + + + ++All constructors should initialize data members +in the member initializer list rather than in the body of the constructor. +
+ ++A class with virtual functions or virtual bases +should have a virtual destructor. +
+ + + ++Single argument constructors should nearly always be declared explicit. +
+ ++Conversion operators should be avoided. +
+ + + + ++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. +
+ + + + ++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. +
+ + + + ++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. +
+ + + + ++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. +
+ + +
+To avoid excessive compiler size,
+consider implementing non-trivial templates
+on a non-template base class with void*
parameters.
+
+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. +
+ +
+Header files should have neither using
directives
+nor namespace-scope using
declarations.
+
dynamic_cast
+Run-time type information (RTTI) is permitted
+when certain non-default --enable-checking
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 -fno-rtti
.
+
+C-style casts should not be used. +Instead, use C++-style casts. +
+ + + + +
+Exceptions and throw specifications are not permitted
+and the compiler must build cleanly with -fno-exceptions
.
+
+Use of the standard library is permitted. +Note, however, that it is currently not usable with garbage collected data. +
+ ++For compiler messages, indeed any text that needs i18n, +should continue to use the existing facilities. +
+ +
+For long-term code, at least for now,
+we will continue to use printf
style I/O
+rather than <iostream>
style I/O.
+For quick debugging code,
+<iostream>
is permitted.
+
+When structs and/or classes have member functions, +prefer to name data members with a trailing underscore. +
+ ++Template parameter names should use CamelCase, +following the C++ Standard. +
+ + + + ++Note that the rules for classes do not apply to structs. +Structs continue to behave as before. +
+ + ++If the entire class definition fits on a single line, put it on a single line. +Otherwise, use the following rules. +
+ ++Indent protection labels by one space. +
+ ++Indent class members by two spaces. +
+ ++Prefer to put the entire class head on a single line. +
+ ++ ++class gnuclass : base { +
+Otherwise, start the colon of the base list at the beginning of a line. +
+ ++ ++class a_rather_long_class_name +: with_a_very_long_base_name, and_another_just_to_make_life_hard +{ + int member; +}; +
+If the base clause exceeds one line, +move overflowing initializers to the next line and indent by two spaces. +
+ ++ ++class gnuclass +: base1 <template_argument1>, base2 <template_argument1>, + base3 <template_argument1>, base4 <template_argument1> +{ + int member; +}; +
+When defining a class, +
++Semantic constraints may require a different declaration order, +but seek to minimize the potential confusion. +
+ ++Close a class definition +with a right brace, semicolon, optional closing comment, and a new line. +
+ ++ + ++}; // class gnuclass +
+Define all members outside the class definition. +That is, there are no function bodies or member initializers +inside the class definition. +
+ ++Prefer to put the entire member head on a single line. +
+ ++ ++gnuclass::gnuclass() : base_class() +{ + ... +}; +
+When that is not possible, +place the colon of the initializer clause at the beginning of a line. +
+ ++ ++gnuclass::gnuclass() +: base1(), base2(), member1(), member2(), member3(), member4() +{ + ... +}; +
+If the initializer clause exceeds one line, +move overflowing initializers to the next line and indent by two spaces. +
+ ++ ++gnuclass::gnuclass() +: base1(some_expression), base2(another_expression), + member1(my_expressions_everywhere) +{ + ... +}; +
+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. +
+ ++ ++void +very_long_class_name::very_long_function_name( + very_long_type_name arg) +{ +
+Sometimes the class qualifier and function name together exceed 80 characters.
+In this case, break the line before the ::
operator.
+We may wish to do so pre-emptively for all class member functions.
+
+ + ++void +very_long_template_class_name <with, a, great, many, arguments> +::very_long_function_name( + very_long_type_name arg) +{ +
+A declaration following a template parameter list +should not have additional indentation. +
+ +
+Prefer typename
over class
+in template parameter lists.
+
+Prefer an extern "C"
block to a declaration qualifier.
+
+Open an extern "C"
block with the left brace on the same line.
+
+ ++extern "C" { +
+Close an extern "C"
block
+with a right brace, optional closing comment, and a new line.
+
+ ++} // extern "C" +
+Definitions within the body of a namespace are not indented. +
+ ++Open a namespace with the namespace name +followed by a left brace and a new line. +
+ ++ ++namespace gnutool { +
+Close a namespace +with a right brace, optional closing comment, and a new line. +
+ ++ ++} // namespace gnutool +
+Definitions within the body of a namespace are not indented. +
+ +