| Message ID | 571A4F78.5020200@t-online.de |
|---|---|
| State | New |
| Headers | show |
> On Apr 22, 2016, at 12:21 PM, Bernd Schmidt <bernds_cb1@t-online.de> wrote: > > (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? Would you expect people to conform to the abridged version or the full standard? If the full standard, then publishing an abridged version is not a good idea, it will just cause confusion. Let the full standard be the rule, make people read it, and if they didn't bother that's their problem. paul
On 04/22/2016 12:42 PM, Paul_Koning@Dell.com wrote: > >> On Apr 22, 2016, at 12:21 PM, Bernd Schmidt <bernds_cb1@t-online.de> wrote: >> >> (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? > > Would you expect people to conform to the abridged version or the full standard? If the full standard, then publishing an abridged version is not a good idea, it will just cause confusion. Let the full standard be the rule, make people read it, and if they didn't bother that's their problem. And this isn't strictly an abridged version, as it contains information that is not part of the GNU standard. > +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> I note that this patch itself is sent as text/x-patch, which thunderbird handles fine. And apparently so does gmail, if you use the .diff extension; the .patch extension that I have tended to use doesn't work properly, so I guess I'll switch. > +<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. Some headers also use tabs to separate the parameter-list from the function name. Jason
On 04/22/2016 07:21 PM, Bernd Schmidt wrote: > (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? > Probably contrib/clang-format and https://gcc.gnu.org/wiki/FormattingCodeForGCC are also worth mentioning.
On 04/22/2016 10:42 AM, Paul_Koning@Dell.com wrote: > >> On Apr 22, 2016, at 12:21 PM, Bernd Schmidt >> <bernds_cb1@t-online.de> wrote: >> >> (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? > > Would you expect people to conform to the abridged version or the > full standard? If the full standard, then publishing an abridged > version is not a good idea, it will just cause confusion. Let the > full standard be the rule, make people read it, and if they didn't > bother that's their problem. I agree; let's not have two documents that can conflict or get out of sync with each other, unless you can figure out how to extract the abridged document automatically from the full version. I think it's fine to have something on the web pages explaining that all contributions must follow the GNU coding standards (with a link) since code that follows the same formatting conventions throughout is easier to read, and that (in particular) patches must match the style of the surrounding code. -Sandra
On 04/22/2016 09:45 PM, Sandra Loosemore wrote: > On 04/22/2016 10:42 AM, Paul_Koning@Dell.com wrote: >> Would you expect people to conform to the abridged version or the >> full standard? If the full standard, then publishing an abridged >> version is not a good idea, it will just cause confusion. Let the >> full standard be the rule, make people read it, and if they didn't >> bother that's their problem. > > I agree; let's not have two documents that can conflict or get out of > sync with each other, unless you can figure out how to extract the > abridged document automatically from the full version. Hmm. As for being out-of-date, I'd say the official document is guilty: it talks about how we can use C89 now that it is prevalent enough. Now that I've looked at it again after many years, the document really does seem poorly organized and contains lots of irrelevant information (a huge table of long option names?) I think if we limit our local document to just the basics (and maybe call it a Getting Started guide rather than an abridged form of the GNU coding standards), there's little danger of it going out of date, and I still think having it would improve our documentation. Bernd
Bernd Schmidt <bernds_cb1@t-online.de> writes: > (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? The patch got some slightly negative reactions, so to balance things out: it looks like a good intro to me FWIW. A couple of nits: > +<p>There should be a space before open-parentheses and after commas. > +We also use spaces around binary operators.</p> I realise it's trying to be short, but the first rule doesn't account for things like "((int) a + b) * 3" and "-(int) 3". Maybe "There should be a space between a function name and the opening parenthesis?". Doesn't cover macros of course. > +<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>. s/being/begin/. Thanks, Richard
On 04/22/2016 12:21 PM, Bernd Schmidt wrote: > (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? Despite the comments downthread, I think that abridged versions of longish standards documents are always a good idea. They need to be maintained, usually reactively, and that's fine. It gives a new contributor something to read that's short enough to provide the salient points for an initial patch/review cycle. The point is to get better incrementally. Nobody is ever perfect the first time. I especially like that Jason caught on that your document is actually *more* than just the GNU Coding Standard, and that where the standard is underspecified the projects have their own conventions. For examples just look at: https://sourceware.org/glibc/wiki/Style_and_Conventions However, in the end, I think that yet-another-document is not the solution we want. What we actually need is a program that just formats your source according to the GNU Coding Style and that way you can always tell your users "Run indent" and be done with it. The output of such a program should always be considered correct, and if it's not, we should fix it immediately. Why can't we use indent? If we can't use indent, what do we need to solve this problem? At the end of the day I never want to see another comment about code formatting because the user used X and X always formats code correctly.
On 05/02/2016 02:40 PM, Carlos O'Donell wrote: > > However, in the end, I think that yet-another-document is not the > solution we want. What we actually need is a program that just formats > your source according to the GNU Coding Style and that way you can always > tell your users "Run indent" and be done with it. The output of such a > program should always be considered correct, and if it's not, we should > fix it immediately. > > Why can't we use indent? Sadly, "indent" simply breaks c++ code. I think the solution here is clang-format with a suitable clang-format configuration file. One has been started (gcc/contrib/clang-format), but it's not yet complete. > > At the end of the day I never want to see another comment about code > formatting because the user used X and X always formats code correctly. Amen. jeff
Jeff Law <law@redhat.com> writes: > On 05/02/2016 02:40 PM, Carlos O'Donell wrote: >> >> However, in the end, I think that yet-another-document is not the >> solution we want. What we actually need is a program that just formats >> your source according to the GNU Coding Style and that way you can always >> tell your users "Run indent" and be done with it. The output of such a >> program should always be considered correct, and if it's not, we should >> fix it immediately. >> >> Why can't we use indent? > Sadly, "indent" simply breaks c++ code. > > I think the solution here is clang-format with a suitable clang-format > configuration file. One has been started (gcc/contrib/clang-format), > but it's not yet complete. How far are you intending to go with that though? I'd hate to see a tool become the final authority on coding standards. For one thing it means that everyone will need exactly the same version of clang-format installed (a la autoconf) in order for all the submissions to agree. If we ever did upgrade to a newer version, the formatting rules for the codebase are likely to change en masse to whatever the new clang-format says is correct. Presumably we might need to keep more than one version of the formatter around, depending on which branch we're working on. And sometimes there are multiple acceptable ways of writing the same code. Which wins is an aesthetic choice, which tools tend to be bad at handling. E.g. if a parameter list is too long for a line, there's often a choice of how to balance the parameters across multiple lines, with some being more readable than others. I wouldn't want the one chosen by a formatting tool to be the only acceptable one. And sometimes people split "if" conditions over multiple lines even when they would fit on one line, since the split version seems more readable. Again I wouldn't want a tool to be the final judge of which is right. Also, reformatting a statement over more lines isn't always the best way of dealing with long lines. Sometimes it's better to split it into separate statements instead. That too is a choice that tools are bad at making. (E.g. if you introduce a temporary variable, what should it be called?) There are exceptions to rules too. E.g. I don't think it's required to end a comment with a full stop if the comment ends with code. /* This is to handle statements like: i++; */ is IMO correct, rather than: /* This is to handle statements like: i++;. */ or: /* This is to handle statements like: i++; . */ I doubt any tool is going to be good enough to make that kind of distinction. (E.g. you can't rely on the semicolon if quoting Fortran code, or a .def style macro invocation.) And if the tool isn't the final authority, and it does still remain a human choice, then... >> At the end of the day I never want to see another comment about code >> formatting because the user used X and X always formats code correctly. > Amen. ...this kind of comment is still going to occur. And clear documentation should help when it does. Also, coding standards and the scope of Bernd's document are more than formatting. E.g. take your comment in a recent thread about not adding "()" when referring to a function in comments. Even clang-format is unlikely to be smart enough to know whether a particular () is acceptable or not. (It would be acceptable in a quoted code snippet but not in a normal sentence.) Also, the tool wouldn't know when argument names need to be capitalised in comments, etc. Sometimes argument names are English words and comments contain a mixture of both uses. Bernd's document talked about those kinds of details too. Sorry for the rant :-) Maybe I'm just jaded by past experience with automatic formatting tools. E.g. we internally use(d?) check_GNU_style.sh to check patches before submission and it seemed to produce far more false positives than true positives. (I'm not sure it ever produced what I'd consider a true positive for me, although I did sometimes do what it said even if I disagreed, as the path of least resistance.) That's not to say the script is bad, just that it shouldn't always be taken literally. Obviously clang-format is smarter than check_GNU_style.sh but I think the same principle applies. Thanks, Richard
On 05/03/2016 03:59 PM, Richard Sandiford wrote: > Jeff Law <law@redhat.com> writes: >> On 05/02/2016 02:40 PM, Carlos O'Donell wrote: >>> >>> However, in the end, I think that yet-another-document is not the >>> solution we want. What we actually need is a program that just formats >>> your source according to the GNU Coding Style and that way you can always >>> tell your users "Run indent" and be done with it. The output of such a >>> program should always be considered correct, and if it's not, we should >>> fix it immediately. >>> >>> Why can't we use indent? >> Sadly, "indent" simply breaks c++ code. >> >> I think the solution here is clang-format with a suitable clang-format >> configuration file. One has been started (gcc/contrib/clang-format), >> but it's not yet complete. > > How far are you intending to go with that though? As far as it takes to make the process of submitting patches less painful for new contributors and sensible for maintainers? If we end up with one tool per branch then we did it wrong. In glibc I'm happy to retroactively say the newest formatting tool is always right for all branches barring expert intervention. > And if the tool isn't the final authority, and it does still remain > a human choice, then... We *are* the community, so yes, there is a final line in the sand where a sensible expert maintainer may tell you "yeah but" and ask you to change the code to make it more legible. However, 99% of the changes are now just going to be automatic. >>> At the end of the day I never want to see another comment about code >>> formatting because the user used X and X always formats code correctly. >> Amen. > > ...this kind of comment is still going to occur. And clear documentation > should help when it does. Yes, it will occur, but the frequency should be much reduced. I also agree that clear documentation helps, so I don't disparage Bernd's work here, I think it's great. I just think that the most important next step here is a submission code formatting tool. > Also, coding standards and the scope of Bernd's document are more > than formatting. E.g. take your comment in a recent thread about not > adding "()" when referring to a function in comments. Even clang-format > is unlikely to be smart enough to know whether a particular () is > acceptable or not. (It would be acceptable in a quoted code snippet > but not in a normal sentence.) Also, the tool wouldn't know when > argument names need to be capitalised in comments, etc. Sometimes > argument names are English words and comments contain a mixture of > both uses. Bernd's document talked about those kinds of details too. Agreed. That's minor. > Sorry for the rant :-) Maybe I'm just jaded by past experience with > automatic formatting tools. E.g. we internally use(d?) check_GNU_style.sh > to check patches before submission and it seemed to produce far more > false positives than true positives. (I'm not sure it ever produced > what I'd consider a true positive for me, although I did sometimes do > what it said even if I disagreed, as the path of least resistance.) > That's not to say the script is bad, just that it shouldn't always be > taken literally. That's a shame and a clear indicator the script is wrong or the technology wasn't around for us to do the kinds of things we wanted. > Obviously clang-format is smarter than check_GNU_style.sh but I think > the same principle applies. If we get one false positive out of the new checker we've done something wrong. It should strive to give output that everyone agrees is 100% correct barring optinal aesthetic choices. This way the tool is run, a reviewer looks at the patch, and final comments are made on the style. That's what I'd like to see for glibc. $0.02.
On Tue, 3 May 2016, Richard Sandiford wrote: > And sometimes there are multiple acceptable ways of writing the same code. > Which wins is an aesthetic choice, which tools tend to be bad at handling. > E.g. if a parameter list is too long for a line, there's often a choice > of how to balance the parameters across multiple lines, with some being > more readable than others. I wouldn't want the one chosen by a formatting > tool to be the only acceptable one. I'd call that a bug in the tool. It shouldn't be switching between valid formatting styles unless explicitly asked to, even if the formatting style seen is not one the tool would itself produce from badly formatted code. > And sometimes people split "if" conditions over multiple lines even when > they would fit on one line, since the split version seems more readable. > Again I wouldn't want a tool to be the final judge of which is right. Like the above -- as long as it's correct it should be left alone even if it's "suboptimal". FWIW, Maciej
On 05/03/2016 09:59 PM, Richard Sandiford wrote: > > And sometimes there are multiple acceptable ways of writing the same code. > Which wins is an aesthetic choice, which tools tend to be bad at handling. > E.g. if a parameter list is too long for a line, there's often a choice > of how to balance the parameters across multiple lines, with some being > more readable than others. I wouldn't want the one chosen by a formatting > tool to be the only acceptable one. I have all the same reservations about using tools for this. We don't call it "style" for nothing, it is not purely mechanical and until we have general-purpose AI I don't believe computers can do a satisfactory job. I've seen attempts to do so in the past, and they have failed - you invariably end up with humans contorting their code to have it pass the checker, which is entirely counterproductive. Bernd
On 05/03/2016 06:39 PM, Bernd Schmidt wrote: > On 05/03/2016 09:59 PM, Richard Sandiford wrote: >> >> And sometimes there are multiple acceptable ways of writing the >> same code. Which wins is an aesthetic choice, which tools tend to >> be bad at handling. E.g. if a parameter list is too long for a >> line, there's often a choice of how to balance the parameters >> across multiple lines, with some being more readable than others. >> I wouldn't want the one chosen by a formatting tool to be the only >> acceptable one. > > I have all the same reservations about using tools for this. We don't > call it "style" for nothing, it is not purely mechanical and until we > have general-purpose AI I don't believe computers can do a > satisfactory job. I've seen attempts to do so in the past, and they > have failed - you invariably end up with humans contorting their code > to have it pass the checker, which is entirely counterproductive. This would be silly. I'd never impose the tool as a commit blocker. We have strayed from the initial goal: Help new developers submit well formatted patches, and learn by example using a tool.
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>