GNU coding standards: Difference between revisions

Revision as of 23:14, 18 February 2006

Latest revision as of 20:20, 8 August 2025

(76 intermediate revisions by 60 users not shown)

Line 1:

{{More footnotes|date=September 2009}}

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.

{{about||the quantum error correcting code|gnu code}}

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

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 GNU Coding Standards were written by [[Richard Stallman]] and other GNU Project volunteers. The standards document is part of the [[GNU Project]] and is available from the GNU website. Though it focuses on writing [[free software]] for GNU in [[C (programming language)|C]], much of it can be applied more generally. In particular, the GNU Project encourages its contributors to always try to follow the standards—whether or not their programs are implemented in C.

== Indentation ==

==Code formatting==

Here is one example of the indentation:

The GNU Coding Standards specify exactly how to format most [[C (programming language)|C programming language]] constructs. Here is a characteristic example:

int main()

{

foo(bar);

}

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.

<syntaxhighlight lang="c">

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.

int

main (int argc, char *argv[])

{

struct gizmo foo;

fetch_gizmo (&foo, argv[1]);

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

check:

foo()

if (foo.type == MOOMIN)

{

ifputs (foo"It's ==a barmoomin.");

else if (foo.bar < GIZMO_SNUFKIN_THRESHOLD / 2

{

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

puts(bar);

&& foo.bar < GIZMO_SNUFKIN_THRESHOLD)

}

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

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.

{

frobnicate (&foo, GIZMO_SNUFKIN_THRESHOLD,

&barney, &wilma, &fred);

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

}

while (foo.bar >= GIZMO_SNUFKIN_THRESHOLD);

store_size (wilma);

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

goto check;

do

{ }

foo(bar);

}

while (foo == bar)

return 0;

== Variable Declaration ==

}

</syntaxhighlight>

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

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.

Being tightly integrated with the GNU system, [[GNU Emacs]] provides automatic formatting of C code to match the GNU coding standards.<ref>{{cite web |url=https://www.gnu.org/software/emacs/manual/html_mono/ccmode.html#index-GNU-style|title=CC Mode Manual|access-date=2025-04-08}}</ref> Rather than manually modifying code formatting in a way that strays from the GNU coding standards, the formatted layout of the code can be tweaked by writing it in a more Emacs-friendly form—for example, by inserting additional parentheses.

Examples:

===Splitting long lines===

int foo;

"When you split an expression into multiple lines, split it before an operator, not after one."<ref>{{Cite web|url=https://www.gnu.org/prep/standards/standards.html#Formatting|title=GNU Coding Standards|website=www.gnu.org|language=en|access-date=2020-11-29}}</ref>

int bar;

For example:

OR

<syntaxhighlight lang="c">

if (foo_this_is_long && bar > win (x, y, z)

&& remaining_condition)

</syntaxhighlight>

==Comments==

int foo, bar;

The standards greatly emphasise the importance of [[English-language]] [[Comment (computer programming)|comments]]:

The method:

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

int foo,

bar;

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

is not permitted under the guidelines.

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

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

==Files==

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.

The standards require that all programs be able to operate when <code>/usr</code> and <code>/etc</code> are [[mount (computing)|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.

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.

==Portability==

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

The GNU Coding Standards define the issue of portability in this way: portability in the [[Unix]] world means 'between Unixes'; in a GNU program this kind of portability is desirable, but not vitally important.

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.

According to the standard, portability problems are very limited as GNU programs are designed to be compiled with one compiler, the [[GNU Compiler Collection|GNU C Compiler]], and only run on one system, which is the GNU system.

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.

There is one form of portability problem though, and that is the fact that the standard makes it clear that a program should run on different [[Central processing unit|CPU]] types. The standard says that GNU doesn't and won't support 16-bit systems, but handling all the different 32- and 64-bit systems is absolutely necessary.

== Portability ==

== Gnits standards ==

The GNU coding standards define the issue of portability in this way; portability in the Unix world means 'between Unixes', in a GNU program this kind of portability is desirable, but not vitally important.

The Gnits standards are a collection of [[Standardization|standards]] and recommendations for programming, maintaining, and distributing [[software]]. They are published by a group of [[GNU project]] maintainers who call themselves "Gnits", which is short for "GNU nit-pickers". As such, they represent advice, not [[Free Software Foundation]] or [[GNU]] policy, but parts of the Gnits' standards have seen widespread adoption among [[free software]] programmers in general.

The Gnits standards are extensions to, refinements of, and annotations for the [[GNU Standards]]. However, they are in no way normative in GNU; GNU maintainers are not required to follow them. Nevertheless, maintainers and programmers often find in Gnits standards good ideas on the way to follow GNU Standards themselves, as well as tentative, non-official explanations about why some GNU standards were decided the way they are. There are very few discrepancies between Gnits and GNU standards, and they are always well noted as such.

According to the standard, portability problems are very limited as GNU programs are designed to be compiled with one compiler, the GNU C Compiler and only run on one system, which is the GNU system.

The standards address aspects of [[software architecture]], program behaviour, [[human–computer interaction]], [[C (computer language)|C]] programming, [[Software documentation|documentation]], and [[Software release|software releases]].

There is one form of portability problem though, and that is the fact that the standard makes it clear that a program should run on different CPU types. The standard says that GNU doesn't and won't support 16 bit types, but handling all the different 32 and 64 bit types is absolutely necessary.

As of 2008, the Gnits standards carry a notice that they are moribund and no longer actively maintained, and points readers to the manuals of [[Gnulib]], [[Autoconf]], and [[Automake]], which are said to cover many of the same topics.

== External links ==

== Criticism ==

* [http://www.gnu.org/prep/standards.html Online GNU Coding Standards]

The GNU coding standards are primarily used by GNU projects, though its use is not limited to GNU projects alone.

[[Category:GNU project software]]

The [[Linux kernel]] strongly discourages this style for kernel code, and refers to the style pejoratively: "First off, I’d suggest printing out a copy of the GNU coding standards, and NOT read it. Burn them, it’s a great symbolic gesture.".<ref>{{Cite web|url=https://www.kernel.org/doc/html/v4.10/process/coding-style.html|title=Linux kernel coding style — The Linux Kernel documentation|website=www.kernel.org|language=en|access-date=2017-10-12}}</ref> [[Steve McConnell]], in his book [[Code Complete]], also advises against using this style; he marks a code sample which uses it with a "Coding Horror" icon, symbolizing especially dangerous code, and states that it impedes readability by requiring an extra level of indentation for braces.<ref>{{cite book |title=Code Complete: A practical handbook of software construction |last=McConnell |first=Steve |publisher=Microsoft Press |year=2004 |isbn=0-7356-1967-0 |___location=Redmond, WA |pages=[https://archive.org/details/codecomplete0000mcco/page/746 746–747] |author-link=Steve McConnell |url=https://archive.org/details/codecomplete0000mcco/page/746 }}</ref>

== See also ==

{{Portal|Free and open-source software}}

*[[Gnits standards]]

==References==

{{Reflist}}

==External links==

* [https://www.gnu.org/prep/standards/ The GNU Coding Standards] on the GNU website

* [https://web.archive.org/web/20090304122402/http://www.ronancrowley.com/Eclipse_GNU_Style.xml Eclipse Code Style Formatter for GNU Coding Standards]

{{DEFAULTSORT:Gnu Coding Standards}}

<!-- Categories -->

[[Category:Free software culture and documents]]

[[Category:GNU Project|Coding Standards]]

[[Category:Source code]]

[[Category:Articles with example C code]]