This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
An abridged "Writing C" for the gcc web pages
- From: Bernd Schmidt <bernds_cb1 at t-online dot de>
- To: GCC Patches <gcc-patches at gcc dot gnu dot org>, Gerald Pfeifer <gerald at pfeifer dot com>, carlos at redhat dot com, Bernd Schmidt <bschmidt at redhat dot com>
- Date: Fri, 22 Apr 2016 18:21:12 +0200
- Subject: An abridged "Writing C" for the gcc web pages
- Authentication-results: sourceware.org; auth=none
(Apologies if you get this twice, the mailing list didn't like the html
attachment in the first attempt).
We frequently get malformatted patches, and it's been brought to my
attention that some people don't even make the effort to read the GNU
coding standards before trying to contribute code. TL;DR seems to be the
excuse, and while I find that attitude inappropriate, we could probably
improve the situation by spelling out the most basic rules in an
abridged document on our webpages. Below is a draft I came up with.
Thoughts?
Bernd
Index: htdocs/contribute.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/contribute.html,v
retrieving revision 1.87
diff -d -u -r1.87 contribute.html
--- htdocs/contribute.html 9 Apr 2015 21:49:31 -0000 1.87
+++ htdocs/contribute.html 22 Apr 2016 16:19:12 -0000
@@ -61,7 +61,9 @@
<p>All contributions must conform to the <a
href="http://www.gnu.org/prep/standards_toc.html";>GNU Coding
-Standards</a>. There are also some <a
+Standards</a>. An <a href="writing-c.html">abridged version of
+the C formatting guidelines</a> is available for purposes of getting
+started. There are also some <a
href="codingconventions.html">additional coding conventions for
GCC</a>; these include documentation and testsuite requirements as
well as requirements on code formatting.</p>
--- /dev/null 2016-04-22 12:54:13.474856906 +0200
+++ htdocs/writing-c.html 2016-04-22 18:11:47.222034004 +0200
@@ -0,0 +1,263 @@
+<html>
+<head>
+<meta name="description"
+ content="Getting Started guide for writing C for the GCC project." />
+<meta name="keywords"
+ content="GCC, standards, C, style, patches, contributing" />
+<title>Getting Started Writing C for the GCC project</title>
+</head>
+
+<body>
+
+<h1>Introduction</h1>
+
+<p>This guide is intended as a heavily abridged version of the C
+coding guidelines in the full <a
+href="http://www.gnu.org/prep/standards_toc.html";>GNU Coding
+Standards</a>, which may be too voluminous for someone just looking to
+contribute a short patch to GCC. Here, the focus is mainly on the
+very basic formatting rules and how they apply to GCC. Anyone who
+wishes to become a long-time contributor should still read the full
+document. There is also <a
+href="https://gcc.gnu.org/codingconventions.html";>an additional
+document</a> going into considerably more detail about less common
+cases that may arise.</p>
+
+<p>We care very strongly about ensuring all code in GCC is formatted
+the same way, as inconsistencies can be very distracting and make it
+harder to modify the source. As always, there are exceptions to the
+rules, but they should be rare and only made for good reasons.</p>
+
+<p>When we speak about C formatting guidelines in this document, we
+intend them to be applied to C++ code as well. Obviously there are
+certain situations where the use of C++ features creates new problems,
+and we have not settled on complete solutions in all cases. The most
+important rule is this: when in doubt about anything, carefully
+examine existing code in the area you are changing (or analogous code
+in other files) and try to follow the prevalent style.</p>
+
+<h1>Tools</h1>
+
+<p>We strongly recommend using an editor which understands and
+supports the GNU formatting rules to some degree. GNU emacs is
+designed for this purpose and supports GNU style as the default for C
+formatting, and we recommend it for this reason. However, there are
+also contributors making good use of other editors such as vim. Using
+more exotic tools, such as Eclipse, or Windows-based editors, may
+prove problematic.</p>
+
+<p>GCC has a <code>check_GNU_style.sh</code> script in the
+<code>contrib/</code> directory to verify the formatting in a patch
+file. Some caution is advisable however, as machines are generally
+not very good at applying common sense.</p>
+
+<p>To make sure that a correctly formatted patch doesn't get destroyed
+by email software, it is usually best to send it as an attachment.
+The format should be text/plain so that mail clients such as
+thunderbird can display and quote it, without forcing potential
+reviewers to take extra steps to save it and open it elsewhere before
+being able to look at it.</p>
+
+<h1>Formatting Your Source Code</h1>
+
+<h2>Formatting Basics</h2>
+
+<p>Please keep the length of source lines to 79 characters or less, for
+maximum readability in the widest range of environments.</p>
+
+<p>Tab characters are interpreted as jumps to stops separated by eight
+spaces. Note that editors on certain systems (such as Microsoft
+Windows) may follow different rules by default, so pay special
+attention if you are using such systems.</p>
+
+<p>All leading whitespace should be replaced with tab characters as
+much as possible, but tab characters should not be used in any other
+circumstances. There should never be trailing whitespace, and no
+carriage-return characters at the line end. Blank lines should just
+consist of a newline character.</p>
+
+<p>There should be a space before open-parentheses and after commas.
+We also use spaces around binary operators.</p>
+
+<p>Avoid unnecessary parentheses and braces, except in special cases that
+are described elsewhere in this document. The following example
+shows how not to do it:</p>
+<blockquote><pre><code> if ((a == 0) && (b == 2))
+ {
+ return (z);
+ }
+</code></pre></blockquote>
+
+<p>Instead, this should be written as follows:</p>
+<blockquote><pre><code> if (a == 0 && b == 2)
+ return z;
+</code></pre></blockquote>
+
+<h2>Naming conventions</h2>
+
+<p>Most identifiers should be all lowercase, with underscore
+characters separating individual words. We write
+<code>insn_code_number</code> instead of <code>InsnCodeNumber</code>
+or similar.</p>
+
+<p>Preprocessor macros are generally all uppercase characters, with
+the notable exception of macros that were introduced to replace
+previously existing variable or function names.</p>
+
+<p>The use of <code>_p</code> suffixes in function names such as
+<code>rtx_equal_p</code> is quite widespread in GCC and may be
+unfamiliar. It stands for “predicate”, meaning that the
+function examines its arguments and returns a boolean, generally
+without any other side effects.
+
+<h2>Function Definitions</h2>
+
+<p>Here is an example for the basic layout of a function definition:</p>
+
+<blockquote><pre><code>static char *
+concat (char *s1, char *s2)
+{
+ …
+}
+</code></pre></blockquote>
+
+<p> Note how the function name starts a new line. This is intended to
+make it easy to find a function definition using tools such as grep.
+The outer braces around the function body are also at the start of the
+line, and the body is initially indented by two spaces.</p>
+
+<p>For <code>struct</code> and <code>enum</code> types, likewise put the braces in
+column one:</p>
+<blockquote><pre><code>struct foo
+{
+ int a, b;
+};
+</code></pre></blockquote>
+
+<h2>Formatting the Body of a Function</h2>
+
+<p>We use the following style for indenting C code:</p>
+
+<blockquote><pre><code>if (x < foo (y, z))
+ haha = bar[4] + 5;
+else if (x > 7)
+ baz = z;
+else
+ {
+ while (z)
+ {
+ haha += foo (z, z);
+ z--;
+ }
+ return ++x + bar ();
+ }
+</code></pre></blockquote>
+
+<p>The basic unit of indentation is two spaces. If a block needs to
+be surrounded by braces, these appear on their own line each, and the
+code contained within is indented a further two spaces. As mentioned
+before, certain editors such as GNU emacs understand the indentation
+rules and can apply them automatically.</p>
+
+<h2>Splitting long lines</h2>
+<p>If function arguments don’t fit nicely on one line, split it like this:
+</p>
+<blockquote><pre><code>lots_of_args (int an_integer, long a_long, short a_short,
+ double a_double, float a_float)
+…
+</code></pre></blockquote>
+
+<p>
+This is very similar to how we format long expressions that do not fit on a
+single line:</p>
+
+<blockquote><pre><code>
+ i0_feeds_i2_n = (i0 && (!i0_feeds_i1_n ? insn_a_feeds_b (i0, i2)
+ : (!reg_overlap_mentioned_p (i1dest, i0dest)
+ && reg_overlap_mentioned_p (i0dest, i2src))));
+</code></pre></blockquote>
+
+<p>As you can see, when an expression is so long that it must be split
+across several lines, we enclose it in a set of parentheses. Any part
+of an expression that is continued on a new line should be indented to
+just past the column of its enclosing parentheses to show the logical
+nesting. GNU emacs knows how to do this automatically. We never
+split a line just after an operator other than the comma, so every new
+line in such a multi-line expression begins with an operator. This also
+applies to assignment operators, the difference being that we don't wrap
+such assignments in parentheses but indent them by two spaces:</p>
+<blockquote><pre><code>
+ unnecessarily_long_variable_identifier
+ = extremely_long_function_name (x < 2 && x > 7);
+</code></pre></blockquote>
+
+<p>There is only one case where occasionally an operator may end a line,
+which is braced initializers:</p>
+<blockquote><pre><code>
+struct foo t =
+{
+ …
+}
+</code></pre></blockquote>
+
+<h2>Comments</h2>
+
+<p>In GCC, we use C style comments almost exclusively. With very few
+exceptions, comments should be full sentences, with the first word
+capitalized (unless it is a lower-case identifier) and with two spaces
+after the end of a sentence.</p>
+
+<p>There should be a brief comment at the start of each source file,
+with a line or two about the overall purpose of the file.</p>
+
+<p>Please put a comment on each function saying what the function
+does, what sorts of arguments it gets, and what the possible values of
+arguments mean and are used for. Also explain the significance of the
+return value, if there is one. While variable and parameter names
+should be lower case, when documenting their values, they should be
+referred to in upper case. Thus, “the inode number
+NODE_NUM” rather than “an inode”. Here is an
+example: </p>
+
+<blockquote><pre><code>
+/* Try to split PATTERN found in INSN. This returns NULL_RTX if
+ PATTERN can not be split. Otherwise, it returns an insn sequence.
+ This is a wrapper around split_insns which ensures that the
+ reg_stat vector is made larger if the splitter creates a new
+ register. */
+
+static rtx_insn *
+combine_split_insns (rtx pattern, rtx_insn *insn)
+{
+ …
+}
+</code></pre></blockquote>
+
+<p>Also note that multi-line comments should always be formatted as in
+the previous example. There should not be extra stars at the
+beginning of new lines, and the comment text should being immediately
+after the opening <code>/*</code>. Please put the closing
+<code>*/</code> on the same line as the end of the last sentence,
+except in cases where that would lead to seriously odd-looking
+results.</p>
+
+<p>There should be a comment on each static variable as well, like
+this:</p>
+
+<blockquote><pre><code>/* Nonzero means truncate lines in the display;
+ zero means continue them. */
+int truncate_lines;
+</code></pre></blockquote>
+
+<p>All other comments should be used to document reasoning, rather
+than describing just what the code does. The canonical example of a
+bad comment is as follows:</p>
+
+<blockquote><pre><code>/* Increment I. */
+i++;
+</code></pre></blockquote>
+
+<p>Place comments on separate lines, in front of whatever they are
+documenting, rather than trying to fit them on the same lines.</p>
+
+</body> </html>