GNU coding standards: Difference between revisions

Revision as of 23:14, 18 February 2006

Revision as of 08:02, 2 March 2006

Line 1:

The '''GNU coding standards''' are a set of rules and guidelines for writing [[computer program|program]]s that work consistently within the [[GNU]] system. The standards document is part of the [[GNU Project]] and is available from the GNU website [http://www.gnu.org/prep/standards/]. Though it focuses on writing [[free software]] for GNU in [[C programming language|C]], much of it can be applied more generally. In particular, contributors to the GNU Project should always try to follow the standards — whether or not their programs are implemented in C —, and it can be a good idea for most authors of free Unix programs to follow the standards — whether or not their programs are officially part of the GNU Project. The C code formatting style is well-known within the free software community, but of course anyone can choose to follow it.

The '''GNU Coding Standards''' document the [[programming style]] used by the [[GNU Project]]. Its main purpose is to guide all volunteers in writing portable, robust, and reliable programs; and to provide [[GNU]] tools that behave consistently.

The GNU coding standards only mention coding in one language, [[C_programming_language|C]].

== IndentationCode formatting ==

The GNU coding standards specify exactly how to format most [[C programming language]] constructs. Here is a characteristic example:

Here is one example of the indentation:

''int main()''

main (''int'' argc, ''char'' *argv[])

{

{

foo(bar);

''struct gizmo'' foo;

}

The basic level of indentation puts the curly brackets on one line, indenting them two spaces in. The statement(s) after the brackets are indented four spaces in.

fetch_gizmo (&foo, argv[1]);

<span style="text-decoration: underline">check</span>:

'''if''' (foo.type == MOOMIN)

puts ("It's a moomin.");

'''else if''' (foo.bar < GIZMO_SNUFKIN_THRESHOLD

|| (strcmp (foo.class_name, "snufkin") == 0)

&& foo.bar < GIZMO_SNUFKIN_THRESHOLD / 2))

puts ("It's a snufkin.");

'''else'''

{

''char'' *barney ''/* Pointer to the first character after''

''the last slash in the file name. */''

''int'' wilma; ''/* Approximate size of the universe. */''

''int'' fred; ''/* Max value of the `bar' field. */''

'''do'''

{

frobnicate (&foo, GIZMO_SNUFKIN_THRESHOLD,

&barney, &wilma, &fred);

twiddle (&foo, barney, wilma + fred);

}

'''while''' (foo.bar >= GIZMO_SNUFKIN_THRESHOLD);

store_size (wilma);

'''goto''' check;

}

'''return''' 0;

}

The consistent treatment of blocks as statements (for the purpose of indentation) is a very distinctive feature of the GNU C code formatting style; as is the mantadory space before parentheses. All code formatted in the GNU style has the property that each closing brace, bracket or parenthesis appears ''to the right'' of its corresponding opening delimiter, or in the same column.

For a function, the curly brackets should be on the first line, on separate lines. The body of the function should be indented two spaces in.

As a general principle, [[GNU Emacs]] can be considered a reliable authority on the GNU code formatting style. As such, it is desirable that any piece of code that looks ugly when indented by Emacs is changed into a more Emacs-friendly form — for example, by inserting additional parentheses.

Statements such as the '''if''' statement should be styled like this:

== Comments ==

foo()

{

if (foo == bar)

{

puts(bar);

}

}

The standards greatly emphasise the importance of English language comments:

Each statement (in this case, '''if''') should be indented from the starting curly bracket. If the statement is a compound statement the curly brackets of its own should be indented two more spaces judging by the statement's position.

<blockquote>Please write the comments in a GNU program in English, because English is the one language that nearly all programmers in all countries can read. If you do not write English well, please write comments in English as well as you can, then ask other people to help rewrite them. If you can't write comments in English, please find someone to work with you and translate your comments into English.</blockquote>

'''do-while''' statements should be written like this:

do

{

foo(bar);

}

while (foo == bar)

== Variable Declaration ==

Variables are declared each on one line, or two of the same sort on one line. The former is preferred in the GNU coding style.

Examples:

int foo;

int bar;

OR

int foo, bar;

The method:

int foo,

bar;

is not permitted under the guidelines.

== Comments ==

Based on the standard, all comments should be in [[English_language|English]]. Each comment should have basic punctuation, but if a lower case identifier comes in the start of a sentence, one is not meant to capitalise it.

According to the standard, a brief comment at the top should explain the program use. This comment should be at the top of the source file containing the main() function.

Comments should also be at the top of functions, explaining what they do and what arguments they receive. To the standard, it is not necessary to duplicate the meaning of the functions arguments, if they are being used in a customary fashion.

The standard determines that there is no need to re-state the name of the function, the reader can see it for his or her self.

Comments should consist of complete, capitalized sentences, each followed by two spaces (so that Emacs can tell where one sentence ends and the next begins).

Every '''#endif''' should have a comment, explaining the condition that is being ended and its sense. Also, every '''#else''' statement should have the same sort of comment after it.

The standard asks that when a programmer enters a comment, the standard asks that two spaces are put on the end of the sentence so that the Emacs sentence commands work.

For long or complex preprocessor conditionals, every <code>#else</code> and <code>#endif</code> should have a comment explaining the condition for the code below (for <code>#else</code>) or above (for <code>#endif</code>).

== Files (temporary, configuration and/or backups) ==

== Files ==

The GNU coding standard tells where to save your temporary, configuration or backup files. It recommends to not assume that /etc or /usr are writeable. A program should have the ability to keep files somewhere else.

The standards require that all programs be able to operate when <code>/usr</code> and <code>/etc</code> are mounted read-only. Therefore, files that are modified for internal purposes (log files, lock files, temporary files, etc.) should not be stored in either <code>/usr</code> or <code>/etc</code>. An exception is made for programs whose job it is to update system configuration files in <code>/etc</code>. Another exception is made for storing files in a directory when the user has explicitly asked to modify a file in the same directory.

To this rule, there are two exceptions, one is that /etc is a place to hold system configuration information, the other is that if a user explicitly asks to store files in a directory, it is reasonable of the program to store the rest of the files in the same directory.

== Portability ==

Line 84 ⟶ 70:

== External links ==

* [http://www.gnu.org/prep/standards.html OnlineThe GNU Coding Standards] on the GNU website

[[Category:GNU project software]]