GCC Coding Conventions

There are some additional coding conventions for code in GCC, beyond those in the GNU Coding Standards. Some existing code may not follow these conventions, but they must be used for new code. If changing existing code to follow these conventions, it is best to send changes to follow the conventions separately from any other changes to the code.

Documentation

Documentation, both of user interfaces and of internals, must be maintained and kept up to date. In particular:

ChangeLogs

GCC requires ChangeLog entries for documentation changes; for the web pages (apart from java/ and libstdc++/) the CVS commit logs are sufficient.

See also what the GNU Coding Standards have to say about what goes in ChangeLogs; in particular, descriptions of the purpose of code and changes should go in comments rather than the ChangeLog, though a single line overall description of the changes may be useful above the ChangeLog entry for a large batch of changes.

For changes that are ported from another branch, we recommend to use a single entry whose body contains a verbatim copy of the original entries describing the changes on that branch, possibly preceded by a single-line overall description of the changes.

There is no established convention on when ChangeLog entries are to be made for testsuite changes; see messages 1 and 2.

If your change fixes a PR, put PR java/58 (where java/58 is the actual number of the PR) at the top of the ChangeLog entry.

Portability

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. 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 library functions if not present on the system used, so those functions may be freely used in GCC. In particular, the ISO C string functions memcmp, memcpy, memmove, memset, strchr and strrchr are preferred to the old functions bcmp, bcopy, bzero, index and rindex; see messages 1 and 2. The older functions must no longer be used in GCC; apart from index, these identifiers are poisoned to prevent their use.

Machine-independent files may contain conditionals on features of a particular system, but should never contain conditionals such as #ifdef __hpux__ on the name or version of a particular system. Exceptions may be made to this on a release branch late in 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 their first use. Function prototypes should only be used when necessary, to break mutually recursive cycles.

Makefiles

touch should never be used in GCC Makefiles. Instead of touch foo always use $(STAMP) foo.

Testsuite Conventions

Every language or library feature, whether standard or a GNU extension, and every warning GCC can give, should have testcases thoroughly covering both its specification and its implementation. Every bug fixed should have a testcase to detect if the bug recurs.

The testsuite READMEs discuss the requirement to use abort () for runtime failures and exit (0) for success. For compile-time tests, a trick taken from autoconf may be used to evaluate expressions: a declaration extern char x[(EXPR) ? 1 : -1]; will compile successfully if and only if EXPR is nonzero.

Where appropriate, testsuite entries should include comments giving their origin: the people who added them or submitted the bug report they relate to, possibly with a reference to a PR in our bug tracking system. There are some copyright guidelines on what can be included in the testsuite.

If a testcase itself is incorrect, but there's a possibility that an improved testcase might fail on some platform where the incorrect testcase passed, the old testcase should be removed and a new testcase (with a different name) should be added. This helps automated regression-checkers distinguish a true regression from an improvement to the test suite.

Miscellaneous Conventions

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_MARKs 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.

Spelling, terminology and markup

The following conventions of spelling and terminology apply throughout GCC, including the manuals, web pages, diagnostics, comments, and (except where they require spaces or hyphens to be used) function and variable names, although consistency in user-visible documentation and diagnostics is more important than that in comments and code. The following table lists some simple cases:

Use......instead ofRationale
American spelling (in particular -ize, -or) British spelling (in particular -ise, -our)
"32-bit" (adjective) "32 bit"
"back end" (noun) "back-end" or "backend"
"back-end" (adjective) "back end" or "backend"
"bit-field" "bit field" or "bitfield" Spelling used in C and C++ standards
"built-in" as an adjective ("built-in function") or "built in" "builtin" "builtin" isn't a word
"ColdFire" "coldfire" or "Coldfire"
"dependent" (adjective), "dependence", "dependency" "dependant", "dependance", "dependancy"
"enumerated" "enumeral" Terminology used in C and C++ standards
"epilogue" "epilog" Established convention
"front end" (noun) "front-end" or "frontend"
"front-end" (adjective) "front end" or "frontend"
"GNU/Linux" (except in reference to the kernel) "Linux" or "linux" or "Linux/GNU"
"lowercase" "lower case" or "lower-case"
"H8S" "H8/S"
"Microsoft Windows" "Windows"
"MIPS" "Mips" or "mips"
"nonzero" "non-zero" or "non zero"
"Objective-C" "Objective C"
"prologue" "prolog" Established convention
"PowerPC" "powerpc", "powerPC" or "PowerPc"
"SPARC" "Sparc" or "sparc"
"testcase", "testsuite" "test-case" or "test case", "test-suite" or "test suite"
"uppercase" "upper case" or "upper-case"
"VAX", "VAXen", "MicroVAX" "vax" or "Vax", "vaxen" or "vaxes", "microvax" or "microVAX"

"GCC" should be used for the GNU Compiler Collection, both generally and as the GNU C Compiler in the context of compiling C; "G++" for the C++ compiler; "gcc" and "g++" (lowercase), marked up with @command when in Texinfo, for the commands for compilation when the emphasis is on those; "GNU C" and "GNU C++" for language dialects; and try to avoid the older term "GNU CC".

Use a comma after "e.g." or "i.e." if and only if it is appropriate in the context and the slight pause a comma means helps the reader; do not add them automatically in all cases just because some style guides say so. (In Texinfo manuals, @: should to be used after "e.g." and "i.e." when a comma isn't used.)

In Texinfo manuals, Texinfo 4.0 features may be used, and should be used where appropriate. URLs should be marked up with @uref; email addresses with @email; command-line options with @option; names of commands with @command; environment variables with @env. NULL should be written as @code{NULL}. Tables of contents should come just after the title page; printed manuals will be formatted (for example, by make dvi) using texi2dvi which reruns TeX until cross-references stabilize, so there is no need for a table of contents to go at the end for it to have correct page numbers. The @refill feature is obsolete and should not be used. All manuals should use @dircategory and @direntry to provide Info directory information for install-info.

It is useful to read the Texinfo manual. Some general Texinfo style issues discussed in that manual should be noted:

Upstream packages

Some files and packages in the GCC source tree are imported from elsewhere, and we want to minimize divergence from their upstream sources. The following files should be updated only according to the rules set below: