Skip to content

L
linux
Commit d8dbbbc5 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet
Browse files
Options

Documentation/CodingStyle: Convert to ReST markup 

- Fix all chapter identation;
- add c blocks where needed;
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 81f10d19
Hide whitespace changes
Inline Side-by-side
Showing with 182 additions and 79 deletions
Documentation/CodingStyle
View file @ d8dbbbc5
Linux kernel coding style
Linux kernel coding style
=========================
This is a short document describing the preferred coding style for the
linux kernel. Coding style is very personal, and I won't _force_ my
......@@ -13,7 +13,8 @@ and NOT read it. Burn them, it's a great symbolic gesture.
Anyway, here goes:
Chapter 1: Indentation
1) Indentation
--------------
Tabs are 8 characters, and thus indentations are also 8 characters.
There are heretic movements that try to make indentations 4 (or even 2!)
......@@ -39,6 +40,8 @@ The preferred way to ease multiple indentation levels in a switch statement is
to align the "switch" and its subordinate "case" labels in the same column
instead of "double-indenting" the "case" labels. E.g.:
.. code-block:: c
switch (suffix) {
case 'G':
case 'g':
......@@ -59,6 +62,8 @@ instead of "double-indenting" the "case" labels. E.g.:
Don't put multiple statements on a single line unless you have
something to hide:
.. code-block:: c
if (condition) do_this;
do_something_everytime;
......@@ -71,7 +76,8 @@ used for indentation, and the above example is deliberately broken.
Get a decent editor and don't leave whitespace at the end of lines.
Chapter 2: Breaking long lines and strings
2) Breaking long lines and strings
----------------------------------
Coding style is all about readability and maintainability using commonly
available tools.
......@@ -87,7 +93,8 @@ with a long argument list. However, never break user-visible strings such as
printk messages, because that breaks the ability to grep for them.
Chapter 3: Placing Braces and Spaces
3) Placing Braces and Spaces
----------------------------
The other issue that always comes up in C styling is the placement of
braces. Unlike the indent size, there are few technical reasons to
......@@ -95,6 +102,8 @@ choose one placement strategy over the other, but the preferred way, as
shown to us by the prophets Kernighan and Ritchie, is to put the opening
brace last on the line, and put the closing brace first, thusly:
.. code-block:: c
if (x is true) {
we do y
}
......@@ -102,6 +111,8 @@ brace last on the line, and put the closing brace first, thusly:
This applies to all non-function statement blocks (if, switch, for,
while, do). E.g.:
.. code-block:: c
switch (action) {
case KOBJ_ADD:
return "add";
......@@ -116,6 +127,8 @@ while, do). E.g.:
However, there is one special case, namely functions: they have the
opening brace at the beginning of the next line, thus:
.. code-block:: c
int function(int x)
{
body of function
......@@ -131,12 +144,16 @@ the cases where it is followed by a continuation of the same statement,
ie a "while" in a do-statement or an "else" in an if-statement, like
this:
.. code-block:: c
do {
body of do-loop
} while (condition);
and
.. code-block:: c
if (x == y) {
..
} else if (x > y) {
......@@ -155,11 +172,15 @@ comments on.
Do not unnecessarily use braces where a single statement will do.
.. code-block:: c
if (condition)
action();
and
.. code-block:: none
if (condition)
do_this();
else
......@@ -168,6 +189,8 @@ and
This does not apply if only one branch of a conditional statement is a single
statement; in the latter case use braces in both branches:
.. code-block:: c
if (condition) {
do_this();
do_that();
......@@ -175,50 +198,60 @@ statement; in the latter case use braces in both branches:
otherwise();
}
3.1: Spaces
3.1) Spaces
***********
Linux kernel style for use of spaces depends (mostly) on
function-versus-keyword usage. Use a space after (most) keywords. The
notable exceptions are sizeof, typeof, alignof, and __attribute__, which look
somewhat like functions (and are usually used with parentheses in Linux,
although they are not required in the language, as in: "sizeof info" after
"struct fileinfo info;" is declared).
although they are not required in the language, as in: ``sizeof info`` after
``struct fileinfo info;`` is declared).
So use a space after these keywords:
So use a space after these keywords::
if, switch, case, for, do, while
but not with sizeof, typeof, alignof, or __attribute__. E.g.,
.. code-block:: c
s = sizeof(struct file);
Do not add spaces around (inside) parenthesized expressions. This example is
*bad*:
**bad**:
.. code-block:: c
s = sizeof( struct file );
When declaring pointer data or a function that returns a pointer type, the
preferred use of '*' is adjacent to the data name or function name and not
preferred use of '\*' is adjacent to the data name or function name and not
adjacent to the type name. Examples:
.. code-block:: c
char *linux_banner;
unsigned long long memparse(char *ptr, char **retptr);
char *match_strdup(substring_t *s);
Use one space around (on each side of) most binary and ternary operators,
such as any of these:
such as any of these::
= + - < > * / % | & ^ <= >= == != ? :
but no space after unary operators:
but no space after unary operators::
& * + - ~ ! sizeof typeof alignof __attribute__ defined
no space before the postfix increment & decrement unary operators:
no space before the postfix increment & decrement unary operators::
++ --
no space after the prefix increment & decrement unary operators:
no space after the prefix increment & decrement unary operators::
++ --
......@@ -237,7 +270,8 @@ of patches, this may make later patches in the series fail by changing their
context lines.
Chapter 4: Naming
4) Naming
---------
C is a Spartan language, and so should your naming be. Unlike Modula-2
and Pascal programmers, C programmers do not use cute names like
......@@ -270,16 +304,22 @@ problem, which is called the function-growth-hormone-imbalance syndrome.
See chapter 6 (Functions).
Chapter 5: Typedefs
5) Typedefs
-----------
Please don't use things like "vps_t".
It's a _mistake_ to use typedef for structures and pointers. When you see a
.. code-block:: c
vps_t a;
in the source, what does it mean?
In contrast, if it says
.. code-block:: c
struct virtual_container *a;
you can actually tell what "a" is.
......@@ -344,7 +384,8 @@ In general, a pointer, or a struct that has elements that can reasonably
be directly accessed should _never_ be a typedef.
Chapter 6: Functions
6) Functions
------------
Functions should be short and sweet, and do just one thing. They should
fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
......@@ -372,8 +413,10 @@ and it gets confused. You know you're brilliant, but maybe you'd like
to understand what you did 2 weeks from now.
In source files, separate functions with one blank line. If the function is
exported, the EXPORT* macro for it should follow immediately after the closing
function brace line. E.g.:
exported, the **EXPORT** macro for it should follow immediately after the
closing function brace line. E.g.:
.. code-block:: c
int system_is_up(void)
{
......@@ -386,7 +429,8 @@ Although this is not required by the C language, it is preferred in Linux
because it is a simple way to add valuable information for the reader.
Chapter 7: Centralized exiting of functions
7) Centralized exiting of functions
-----------------------------------
Albeit deprecated by some people, the equivalent of the goto statement is
used frequently by compilers in form of the unconditional jump instruction.
......@@ -409,9 +453,11 @@ The rationale for using gotos is:
- unconditional statements are easier to understand and follow
- nesting is reduced
- errors by not updating individual exit points when making
modifications are prevented
modifications are prevented
- saves the compiler work to optimize redundant code away ;)
.. code-block:: c
int fun(int a)
{
int result = 0;
......@@ -436,6 +482,8 @@ The rationale for using gotos is:
A common type of bug to be aware of is "one err bugs" which look like this:
.. code-block:: c
err:
kfree(foo->bar);
kfree(foo);
......@@ -445,6 +493,8 @@ The bug in this code is that on some exit paths "foo" is NULL. Normally the
fix for this is to split it up into two error labels "err_free_bar:" and
"err_free_foo:":
.. code-block:: c
err_free_bar:
kfree(foo->bar);
err_free_foo:
......@@ -454,7 +504,8 @@ fix for this is to split it up into two error labels "err_free_bar:" and
Ideally you should simulate errors to test all exit paths.
Chapter 8: Commenting
8) Commenting
-------------
Comments are good, but there is also a danger of over-commenting. NEVER
try to explain HOW your code works in a comment: it's much better to
......@@ -476,6 +527,8 @@ for details.
The preferred style for long (multi-line) comments is:
.. code-block:: c
/*
* This is the preferred style for multi-line
* comments in the Linux kernel source code.
......@@ -488,6 +541,8 @@ The preferred style for long (multi-line) comments is:
For files in net/ and drivers/net/ the preferred style for long (multi-line)
comments is a little different.
.. code-block:: c
/* The preferred comment style for files in net/ and drivers/net
* looks like this.
*
......@@ -501,7 +556,8 @@ multiple data declarations). This leaves you room for a small comment on each
item, explaining its use.
Chapter 9: You've made a mess of it
9) You've made a mess of it
---------------------------
That's OK, we all do. You've probably been told by your long-time Unix
user helper that "GNU emacs" automatically formats the C sources for
......@@ -513,38 +569,40 @@ make a good program).
So, you can either get rid of GNU emacs, or change it to use saner
values. To do the latter, you can stick the following in your .emacs file:
(defun c-lineup-arglist-tabs-only (ignored)
"Line up argument lists by tabs, not spaces"
(let* ((anchor (c-langelem-pos c-syntactic-element))
(column (c-langelem-2nd-pos c-syntactic-element))
(offset (- (1+ column) anchor))
(steps (floor offset c-basic-offset)))
(* (max steps 1)
c-basic-offset)))
(add-hook 'c-mode-common-hook
(lambda ()
;; Add kernel style
(c-add-style
"linux-tabs-only"
'("linux" (c-offsets-alist
(arglist-cont-nonempty
c-lineup-gcc-asm-reg
c-lineup-arglist-tabs-only))))))
(add-hook 'c-mode-hook
(lambda ()
(let ((filename (buffer-file-name)))
;; Enable kernel mode for the appropriate files
(when (and filename
(string-match (expand-file-name "~/src/linux-trees")
filename))
(setq indent-tabs-mode t)
(setq show-trailing-whitespace t)
(c-set-style "linux-tabs-only")))))
.. code-block:: none
(defun c-lineup-arglist-tabs-only (ignored)
"Line up argument lists by tabs, not spaces"
(let* ((anchor (c-langelem-pos c-syntactic-element))
(column (c-langelem-2nd-pos c-syntactic-element))
(offset (- (1+ column) anchor))
(steps (floor offset c-basic-offset)))
(* (max steps 1)
c-basic-offset)))
(add-hook 'c-mode-common-hook
(lambda ()
;; Add kernel style
(c-add-style
"linux-tabs-only"
'("linux" (c-offsets-alist
(arglist-cont-nonempty
c-lineup-gcc-asm-reg
c-lineup-arglist-tabs-only))))))
(add-hook 'c-mode-hook
(lambda ()
(let ((filename (buffer-file-name)))
;; Enable kernel mode for the appropriate files
(when (and filename
(string-match (expand-file-name "~/src/linux-trees")
filename))
(setq indent-tabs-mode t)
(setq show-trailing-whitespace t)
(c-set-style "linux-tabs-only")))))
This will make emacs go better with the kernel coding style for C
files below ~/src/linux-trees.
files below ``~/src/linux-trees``.
But even if you fail in getting emacs to do sane formatting, not
everything is lost: use "indent".
......@@ -562,14 +620,15 @@ re-formatting you may want to take a look at the man page. But
remember: "indent" is not a fix for bad programming.
Chapter 10: Kconfig configuration files
10) Kconfig configuration files
-------------------------------
For all of the Kconfig* configuration files throughout the source tree,
the indentation is somewhat different. Lines under a "config" definition
are indented with one tab, while help text is indented an additional two
spaces. Example:
spaces. Example::
config AUDIT
config AUDIT
bool "Auditing support"
depends on NET
help
......@@ -579,9 +638,9 @@ config AUDIT
auditing without CONFIG_AUDITSYSCALL.
Seriously dangerous features (such as write support for certain
filesystems) should advertise this prominently in their prompt string:
filesystems) should advertise this prominently in their prompt string::
config ADFS_FS_RW
config ADFS_FS_RW
bool "ADFS write support (DANGEROUS)"
depends on ADFS_FS
...
......@@ -590,7 +649,8 @@ For full documentation on the configuration files, see the file
Documentation/kbuild/kconfig-language.txt.
Chapter 11: Data structures
11) Data structures
-------------------
Data structures that have visibility outside the single-threaded
environment they are created and destroyed in should always have
......@@ -621,10 +681,13 @@ Remember: if another thread can find your data structure, and you don't
have a reference count on it, you almost certainly have a bug.
Chapter 12: Macros, Enums and RTL
12) Macros, Enums and RTL
-------------------------
Names of macros defining constants and labels in enums are capitalized.
.. code-block:: c
#define CONSTANT 0x12345
Enums are preferred when defining several related constants.
......@@ -636,7 +699,9 @@ Generally, inline functions are preferable to macros resembling functions.
Macros with multiple statements should be enclosed in a do - while block:
#define macrofun(a, b, c) \
.. code-block:: c
#define macrofun(a, b, c) \
do { \
if (a == 5) \
do_this(b, c); \
......@@ -646,6 +711,8 @@ Things to avoid when using macros:
1) macros that affect control flow:
.. code-block:: c
#define FOO(x) \
do { \
if (blah(x) < 0) \
......@@ -657,6 +724,8 @@ function; don't break the internal parsers of those who will read the code.
2) macros that depend on having a local variable with a magic name:
.. code-block:: c
#define FOO(val) bar(index, val)
might look like a good thing, but it's confusing as hell when one reads the
......@@ -669,18 +738,22 @@ bite you if somebody e.g. turns FOO into an inline function.
must enclose the expression in parentheses. Beware of similar issues with
macros using parameters.
.. code-block:: c
#define CONSTANT 0x4000
#define CONSTEXP (CONSTANT | 3)
5) namespace collisions when defining local variables in macros resembling
functions:
#define FOO(x) \
({ \
typeof(x) ret; \
ret = calc_ret(x); \
(ret); \
})
.. code-block:: c
#define FOO(x) \
({ \
typeof(x) ret; \
ret = calc_ret(x); \
(ret); \
})
ret is a common name for a local variable - __foo_ret is less likely
to collide with an existing variable.
......@@ -689,7 +762,8 @@ The cpp manual deals with macros exhaustively. The gcc internals manual also
covers RTL which is used frequently with assembly language in the kernel.
Chapter 13: Printing kernel messages
13) Printing kernel messages
----------------------------
Kernel developers like to be seen as literate. Do mind the spelling
of kernel messages to make a good impression. Do not use crippled
......@@ -723,7 +797,8 @@ already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be
used.
Chapter 14: Allocating memory
14) Allocating memory
---------------------
The kernel provides the following general purpose memory allocators:
kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
......@@ -732,6 +807,8 @@ about them.
The preferred form for passing a size of a struct is the following:
.. code-block:: c
p = kmalloc(sizeof(*p), ...);
The alternative form where struct name is spelled out hurts readability and
......@@ -744,17 +821,22 @@ language.
The preferred form for allocating an array is the following:
.. code-block:: c
p = kmalloc_array(n, sizeof(...), ...);
The preferred form for allocating a zeroed array is the following:
.. code-block:: c
p = kcalloc(n, sizeof(...), ...);
Both forms check for overflow on the allocation size n * sizeof(...),
and return NULL if that occurred.
Chapter 15: The inline disease
15) The inline disease
----------------------
There appears to be a common misperception that gcc has a magic "make me
faster" speedup option called "inline". While the use of inlines can be
......@@ -781,7 +863,8 @@ appears outweighs the potential value of the hint that tells gcc to do
something it would have done anyway.
Chapter 16: Function return values and names
16) Function return values and names
------------------------------------
Functions can return values of many different kinds, and one of the
most common is a value indicating whether the function succeeded or
......@@ -793,7 +876,7 @@ Mixing up these two sorts of representations is a fertile source of
difficult-to-find bugs. If the C language included a strong distinction
between integers and booleans then the compiler would find these mistakes
for us... but it doesn't. To help prevent such bugs, always follow this
convention:
convention::
If the name of a function is an action or an imperative command,
the function should return an error-code integer. If the name
......@@ -815,17 +898,22 @@ result. Typical examples would be functions that return pointers; they use
NULL or the ERR_PTR mechanism to report failure.
Chapter 17: Don't re-invent the kernel macros
17) Don't re-invent the kernel macros
-------------------------------------
The header file include/linux/kernel.h contains a number of macros that
you should use, rather than explicitly coding some variant of them yourself.
For example, if you need to calculate the length of an array, take advantage
of the macro
.. code-block:: c
#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
Similarly, if you need to calculate the size of some structure member, use
.. code-block:: c
#define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
There are also min() and max() macros that do strict type checking if you
......@@ -833,16 +921,21 @@ need them. Feel free to peruse that header file to see what else is already
defined that you shouldn't reproduce in your code.
Chapter 18: Editor modelines and other cruft
18) Editor modelines and other cruft
------------------------------------
Some editors can interpret configuration information embedded in source files,
indicated with special markers. For example, emacs interprets lines marked
like this:
.. code-block:: c
-*- mode: c -*-
Or like this:
.. code-block:: c
/*
Local Variables:
compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
......@@ -851,6 +944,8 @@ Or like this:
Vim interprets markers that look like this:
.. code-block:: c
/* vim:set sw=8 noet */
Do not include any of these in source files. People have their own personal
......@@ -860,7 +955,8 @@ own custom mode, or may have some other magic method for making indentation
work correctly.
Chapter 19: Inline assembly
19) Inline assembly
-------------------
In architecture-specific code, you may need to use inline assembly to interface
with CPU or platform functionality. Don't hesitate to do so when necessary.
......@@ -884,12 +980,15 @@ instructions, put each instruction on a separate line in a separate quoted
string, and end each string except the last with \n\t to properly indent the
next instruction in the assembly output:
.. code-block:: c
asm ("magic %reg1, #42\n\t"
"more_magic %reg2, %reg3"
: /* outputs */ : /* inputs */ : /* clobbers */);
Chapter 20: Conditional Compilation
20) Conditional Compilation
---------------------------
Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c
files; doing so makes code harder to read and logic harder to follow. Instead,
......@@ -913,6 +1012,8 @@ unused, delete it.)
Within code, where possible, use the IS_ENABLED macro to convert a Kconfig
symbol into a C boolean expression, and use it in a normal C conditional:
.. code-block:: c
if (IS_ENABLED(CONFIG_SOMETHING)) {
...
}
......@@ -928,12 +1029,15 @@ At the end of any non-trivial #if or #ifdef block (more than a few lines),
place a comment after the #endif on the same line, noting the conditional
expression used. For instance:
.. code-block:: c
#ifdef CONFIG_SOMETHING
...
#endif /* CONFIG_SOMETHING */
Appendix I: References
Appendix I) References
----------------------
The C Programming Language, Second Edition
by Brian W. Kernighan and Dennis M. Ritchie.
......@@ -953,4 +1057,3 @@ language C, URL: http://www.open-std.org/JTC1/SC22/WG14/
Kernel CodingStyle, by greg@kroah.com at OLS 2002:
http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7