This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
Patch: documenting GCC's coding conventions
- To: <gcc-patches at gcc dot gnu dot org>
- Subject: Patch: documenting GCC's coding conventions
- From: "Joseph S. Myers" <jsm28 at cam dot ac dot uk>
- Date: Wed, 1 Nov 2000 21:47:56 +0000 (GMT)
GCC's coding conventions (beyond the GNU coding standards) don't yet seem
to have been documented. This patch adds a web page documenting those I
could remember and find references for. OK to commit?
(I thought there was a convention for what to do with dates on ChangeLog
entries when backporting changes to a release branch, but couldn't find
any relevant message. There may also be other conventions that have been
decided in the past three years which I've forgotten.)
--- contribute.html.orig Mon Oct 30 10:39:14 2000
+++ contribute.html Wed Nov 1 21:42:37 2000
@@ -21,7 +21,9 @@
<p>All contributions must conform to the <a
href="http://www.gnu.org/prep/standards_toc.html">GNU Coding
Standards</a>. Submissions which do not conform to the standards will
- be returned with a request to reformat the changes.
+ be returned with a request to reformat the changes. There are also
+ some <a href="codingconventions.html">additional coding conventions
+ for GCC</a>.
<h2>Copyright Assignment</h2>
--- /dev/null Fri Sep 11 11:31:59 1998
+++ codingconventions.html Wed Nov 1 21:41:19 2000
@@ -0,0 +1,106 @@
+<html>
+
+<head>
+<title>GCC Coding Conventions</title>
+</head>
+
+<body>
+<h1 align=center>GCC Coding Conventions</h1>
+
+<p>There are some additional coding conventions for code in GCC,
+beyond those in the <a
+href="http://www.gnu.org/prep/standards_toc.html">GNU Coding
+Standards</a>. Some existing code may not follow these conventions,
+but it is preferred to use them in 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.</p>
+
+<h2>Portability</h2>
+
+<p>There are strict requirements for portability of code in GCC to
+older systems whose compilers do not implement the ISO C standard.
+See <a
+href="http://gcc.gnu.org/cgi-bin/cvsweb.cgi/~checkout~/egcs/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>The programs included in GCC are linked with the
+<code>libiberty</code> 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 <code>memcmp</code>, <code>memcpy</code>,
+<code>memmove</code>, <code>memset</code>, <code>strchr</code> and
+<code>strrchr</code> are preferred to the old functions
+<code>bcmp</code>, <code>bcopy</code>, <code>bzero</code>,
+<code>index</code> and <code>rindex</code>; see messages <a
+href="http://gcc.gnu.org/ml/gcc/1998-09/msg01000.html">1</a> and <a
+href="http://gcc.gnu.org/ml/gcc/1998-09/msg01127.html">2</a>, and note
+if changing the form used in existing code that care must be taken
+over the different argument order used by <code>memcpy</code> and
+<code>bcopy</code>, and that <code>bcopy</code> is equivalent to
+<code>memmove</code> though in most cases <code>memcpy</code> is the
+appropriate replacement.</p>
+
+<h2>ChangeLogs</h2>
+
+<p>GCC requires ChangeLog entries for documentation changes (see <a
+href="http://gcc.gnu.org/ml/gcc-bugs/1998-03/msg00564.html">message</a>),
+though for changes to the GCC web pages (as opposed to the
+libstdc++-v3 ones) there is no appropriate ChangeLog file and the CVS
+logs suffice.</p>
+
+<p>There is no established convention on when ChangeLog entries are to
+be made for testsuite changes; see messages <a
+href="http://gcc.gnu.org/ml/gcc/2000-09/msg00287.html">1</a> and <a
+href="http://gcc.gnu.org/ml/gcc/2000-09/msg00290.html">2</a>.</p>
+
+<h2>Testsuite conventions</h2>
+
+<p>The testsuite READMEs discuss the requirement to use <code>abort
+()</code> for runtime failures and <code>exit (0)</code> for success.
+For compile-time tests, a trick from Autoconf may be used to evaluate
+expressions: a declaration <code>extern char x[(EXPR) ? 1 :
+-1];</code> will compile successfully if and only if <code>EXPR</code>
+is nonzero.</p>
+
+<p>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 GNATS. There are
+some <a
+href="http://gcc.gnu.org/ml/gcc/2000-01/msg00593.html">copyright
+guidelines</a> on what can be included in the testsuite.</p>
+
+<h2>Miscellaneous conventions</h2>
+
+<p>Code should generally use <code>abort ()</code> rather than
+<code>assert ()</code> for tests for "can't happen" conditions; see <a
+href="http://gcc.gnu.org/ml/gcc-patches/2000-07/msg01304.html">message</a>.
+Such conditions should not be generated by invalid user input. 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 in GCC should use <code>!x</code> rather than <code>!
+x</code>, and similarly for other unary operators; see <a
+href="http://gcc.gnu.org/ml/gcc/2000-09/msg00524.html">message</a>.
+However, <a href="http://gcc.gnu.org/ml/gcc/2000-09/msg00586.html">a
+space should be used with casts</a>.</p>
+
+<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>
+
+</body>
+</html>
--
Joseph S. Myers
jsm28@cam.ac.uk