GNU coding standards

Last updated

The GNU coding standards are a set of rules and guidelines for writing programs 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, 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.

Contents

Code formatting

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

intmain(intargc,char*argv[]){structgizmofoo;fetch_gizmo(&foo,argv[1]);check:if(foo.type==MOOMIN)puts("It's a moomin.");elseif(foo.bar<GIZMO_SNUFKIN_THRESHOLD/2||(strcmp(foo.class_name,"snufkin")==0)&&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.  */intwilma;/* Approximate size of the universe.  */intfred;/* 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);gotocheck;}return0;}

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.

As a general principle, GNU Emacs can be considered[ by whom? ] a reliable authority on the GNU code formatting style. As such, it is desirable[ according to whom? ] 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.

Splitting long lines

"When you split an expression into multiple lines, split it before an operator, not after one." [1]

For example:

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

Comments

The standards greatly emphasise the importance of English-language comments:

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.

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

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

Files

The standards require that all programs be able to operate when /usr and /etc 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 /usr or /etc. An exception is made for programs whose job it is to update system configuration files in /etc. Another exception is made for storing files in a directory when the user has explicitly asked to modify a file in the same directory.

Portability

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.

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.

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 systems, but handling all the different 32- and 64-bit systems is absolutely necessary.

Criticism

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

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.". [2] 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. [3]

See also

Related Research Articles

The editor war is the rivalry between users of the Emacs and vi text editors. The rivalry has become an enduring part of hacker culture and the free software community.

<span class="mw-page-title-main">GNU Debugger</span> Source-level debugger

The GNU Debugger (GDB) is a portable debugger that runs on many Unix-like systems and works for many programming languages, including Ada, C, C++, Objective-C, Free Pascal, Fortran, Go, and partially others.

An integrated development environment (IDE) is a software application that provides comprehensive facilities to computer programmers for software development. An IDE normally consists of at least a source code editor, build automation tools, and a debugger. Some IDEs, such as NetBeans and Eclipse, contain the necessary compiler, interpreter, or both; others, such as SharpDevelop and Lazarus, do not.

The C preprocessor is the macro preprocessor for the C, Objective-C and C++ computer programming languages. The preprocessor provides the ability for the inclusion of header files, macro expansions, conditional compilation, and line control.

<span class="mw-page-title-main">GNU Project</span> Free software project

The GNU Project is a free software, mass collaboration project announced by Richard Stallman on September 27, 1983. Its goal is to give computer users freedom and control in their use of their computers and computing devices by collaboratively developing and publishing software that gives everyone the rights to freely run the software, copy and distribute it, study it, and modify it. GNU software grants these rights in its license.

In computer programming, an indentation style is a convention governing the indentation of blocks of code to convey program structure. This article largely addresses the free-form languages, such as C and its descendants, but can be applied to most other programming languages, where whitespace is otherwise insignificant. Indentation style is only one aspect of programming style.

Pretty-printing is the application of any of various stylistic formatting conventions to text files, such as source code, markup, and similar kinds of content. These formatting conventions may entail adhering to an indentation style, using different color and typeface to highlight syntactic elements of source code, or adjusting size, to make the content easier for people to read, and understand. Pretty-printers for source code are sometimes called code formatters or beautifiers.

The syntax of the C programming language is the set of rules governing writing of software in the C language. It is designed to allow for programs that are extremely terse, have a close relationship with the resulting object code, and yet provide relatively high-level data abstraction. C was the first widely successful high-level language for portable operating-system development.

In compiler construction, name mangling is a technique used to solve various problems caused by the need to resolve unique names for programming entities in many modern programming languages.

The GNU Assembler, commonly known as gas or as, is the assembler developed by the GNU Project. It is the default back-end of GCC. It is used to assemble the GNU operating system and the Linux kernel, and various other software. It is a part of the GNU Binutils package.

In computer programming, an entry point is the place in a program where the execution of a program begins, and where the program has access to command line arguments.

In computing, a shebang is the character sequence consisting of the characters number sign and exclamation mark at the beginning of a script. It is also called sharp-exclamation, sha-bang, hashbang, pound-bang, or hash-pling.

The C and C++ programming languages are closely related but have many significant differences. C++ began as a fork of an early, pre-standardized C, and was designed to be mostly source-and-link compatible with C compilers of the time. Due to this, development tools for the two languages are often integrated into a single product, with the programmer able to specify C or C++ as their source language.

binfmt_misc is a capability of the Linux kernel which allows arbitrary executable file formats to be recognized and passed to certain user space applications, such as emulators and virtual machines. It is one of a number of binary format handlers in the kernel that are involved in preparing a user-space program to run.

A weak symbol denotes a specially annotated symbol during linking of Executable and Linkable Format (ELF) object files. By default, without any annotation, a symbol in an object file is strong. During linking, a strong symbol can override a weak symbol of the same name. In contrast, in the presence of two strong symbols by the same name, the linker resolves the symbol in favor of the first one found. This behavior allows an executable to override standard library functions, such as malloc(3). When linking a binary executable, a weakly declared symbol does not need a definition. In comparison, a declared strong symbol without a definition triggers an undefined symbol link error.

<span class="mw-page-title-main">GNU Emacs</span> GNU version of the Emacs text editor

GNU Emacs is a free software text editor. It was created by GNU Project founder Richard Stallman, based on the Emacs editor developed for Unix operating systems. GNU Emacs has been a central component of the GNU project and a flagship project of the free software movement. Its name has occasionally been shortened to GNUMACS. The tag line for GNU Emacs is "the extensible self-documenting text editor".

<span class="mw-page-title-main">Unix</span> Family of computer operating systems

Unix is a family of multitasking, multiuser computer operating systems that derive from the original AT&T Unix, whose development started in 1969 at the Bell Labs research center by Ken Thompson, Dennis Ritchie, and others.

Getopt is a C library function used to parse command-line options of the Unix/POSIX style. It is a part of the POSIX specification, and is universal to Unix-like systems. It is also the name of a Unix program for parsing command line arguments in shell scripts.

The write is one of the most basic routines provided by a Unix-like operating system kernel. It writes data from a buffer declared by the user to a given device, such as a file. This is the primary way to output data from a program by directly using a system call. The destination is identified by a numeric code. The data to be written, for instance a piece of text, is defined by a pointer and a size, given in number of bytes.

References

  1. ↑ "GNU Coding Standards". www.gnu.org. Retrieved 2020-11-29.
  2. ↑ "Linux kernel coding style — The Linux Kernel documentation". www.kernel.org. Retrieved 2017-10-12.
  3. ↑ McConnell, Steve (2004). Code Complete: A practical handbook of software construction. Redmond, WA: Microsoft Press. pp.  746–747. ISBN   0-7356-1967-0.
This page is based on this Wikipedia article
Text is available under the CC BY-SA 4.0 license; additional terms may apply.
Images, videos and audio are available under their respective licenses.