leandrof/linux
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation/CodingStyle: improve text layout

Browse Source 
Try to make coding style documentation look a bit more readable and
consistent with the following:

 - indent every code example in C to first tab-stop;
 - surround every code example with empty lines, both top and bottom;
 - remove empty lines where text looked way too spare;
 - do not indent examples in elisp and kconfig;
 - do not do any non-whitespace changes.

Signed-off-by: Pavel Kretov <firegurafiku@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Pavel Kretov 2015-02-16 20:26:18 +03:00 committed by Jonathan Corbet
parent 696156f03f
commit 09677e0ff8
1 changed files with 70 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

137
Documentation/CodingStyle
View File

@ -56,7 +56,6 @@ instead of "double-indenting" the "case" labels. E.g.:
break; break;
} }
Don't put multiple statements on a single line unless you have Don't put multiple statements on a single line unless you have
something to hide: something to hide:
@ -156,25 +155,25 @@ comments on.
Do not unnecessarily use braces where a single statement will do. Do not unnecessarily use braces where a single statement will do.
if (condition) if (condition)
action(); action();
and and
if (condition) if (condition)
do_this(); do_this();
else else
do_that(); do_that();
This does not apply if only one branch of a conditional statement is a single 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: statement; in the latter case use braces in both branches:
if (condition) { if (condition) {
do_this(); do_this();
do_that(); do_that();
} else { } else {
otherwise(); otherwise();
} }
3.1: Spaces 3.1: Spaces
@ -186,8 +185,11 @@ although they are not required in the language, as in: "sizeof info" after
"struct fileinfo info;" is declared). "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 if, switch, case, for, do, while
but not with sizeof, typeof, alignof, or __attribute__. E.g., but not with sizeof, typeof, alignof, or __attribute__. E.g.,
s = sizeof(struct file); s = sizeof(struct file);
Do not add spaces around (inside) parenthesized expressions. This example is Do not add spaces around (inside) parenthesized expressions. This example is
@ -209,12 +211,15 @@ such as any of these:
= + - < > * / % | & ^ <= >= == != ? : = + - < > * / % | & ^ <= >= == != ? :
but no space after unary operators: but no space after unary operators:
& * + - ~ ! sizeof typeof alignof __attribute__ defined & * + - ~ ! 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:
++ -- ++ --
and no space around the '.' and "->" structure member operators. and no space around the '.' and "->" structure member operators.
@ -268,13 +273,11 @@ See chapter 6 (Functions).
Chapter 5: Typedefs Chapter 5: Typedefs
Please don't use things like "vps_t". Please don't use things like "vps_t".
It's a _mistake_ to use typedef for structures and pointers. When you see a It's a _mistake_ to use typedef for structures and pointers. When you see a
vps_t a; vps_t a;
in the source, what does it mean? in the source, what does it mean?
In contrast, if it says In contrast, if it says
struct virtual_container *a; struct virtual_container *a;
@ -372,11 +375,11 @@ 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 exported, the EXPORT* macro for it should follow immediately after the closing
function brace line. E.g.: function brace line. E.g.:
int system_is_up(void) int system_is_up(void)
{ {
return system_state == SYSTEM_RUNNING; return system_state == SYSTEM_RUNNING;
} }
EXPORT_SYMBOL(system_is_up); EXPORT_SYMBOL(system_is_up);
In function prototypes, include parameter names with their data types. In function prototypes, include parameter names with their data types.
Although this is not required by the C language, it is preferred in Linux Although this is not required by the C language, it is preferred in Linux
@ -405,34 +408,34 @@ The rationale for using gotos is:
modifications are prevented modifications are prevented
- saves the compiler work to optimize redundant code away ;) - saves the compiler work to optimize redundant code away ;)
int fun(int a) int fun(int a)
{ {
int result = 0; int result = 0;
char *buffer; char *buffer;
buffer = kmalloc(SIZE, GFP_KERNEL); buffer = kmalloc(SIZE, GFP_KERNEL);
if (!buffer) if (!buffer)
return -ENOMEM; return -ENOMEM;
if (condition1) { if (condition1) {
while (loop1) { while (loop1) {
... ...
}
result = 1;
goto out_buffer;
} }
result = 1; ...
goto out_buffer; out_buffer:
kfree(buffer);
return result;
} }
...
out_buffer:
kfree(buffer);
return result;
}
A common type of bug to be aware of it "one err bugs" which look like this: A common type of bug to be aware of it "one err bugs" which look like this:
err: err:
kfree(foo->bar); kfree(foo->bar);
kfree(foo); kfree(foo);
return ret; return ret;
The bug in this code is that on some exit paths "foo" is NULL. Normally the 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_bar:" and "err_foo:". fix for this is to split it up into two error labels "err_bar:" and "err_foo:".
@ -612,7 +615,7 @@ have a reference count on it, you almost certainly have a bug.
Names of macros defining constants and labels in enums are capitalized. Names of macros defining constants and labels in enums are capitalized.
#define CONSTANT 0x12345 #define CONSTANT 0x12345
Enums are preferred when defining several related constants. Enums are preferred when defining several related constants.
@ -623,28 +626,28 @@ Generally, inline functions are preferable to macros resembling functions.
Macros with multiple statements should be enclosed in a do - while block: Macros with multiple statements should be enclosed in a do - while block:
#define macrofun(a, b, c) \ #define macrofun(a, b, c) \
do { \ do { \
if (a == 5) \ if (a == 5) \
do_this(b, c); \ do_this(b, c); \
} while (0) } while (0)
Things to avoid when using macros: Things to avoid when using macros:
1) macros that affect control flow: 1) macros that affect control flow:
#define FOO(x) \ #define FOO(x) \
do { \ do { \
if (blah(x) < 0) \ if (blah(x) < 0) \
return -EBUGGERED; \ return -EBUGGERED; \
} while(0) } while(0)
is a _very_ bad idea. It looks like a function call but exits the "calling" is a _very_ bad idea. It looks like a function call but exits the "calling"
function; don't break the internal parsers of those who will read the code. 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: 2) macros that depend on having a local variable with a magic name:
#define FOO(val) bar(index, val) #define FOO(val) bar(index, val)
might look like a good thing, but it's confusing as hell when one reads the might look like a good thing, but it's confusing as hell when one reads the
code and it's prone to breakage from seemingly innocent changes. code and it's prone to breakage from seemingly innocent changes.
@ -656,8 +659,8 @@ bite you if somebody e.g. turns FOO into an inline function.
must enclose the expression in parentheses. Beware of similar issues with must enclose the expression in parentheses. Beware of similar issues with
macros using parameters. macros using parameters.
#define CONSTANT 0x4000 #define CONSTANT 0x4000
#define CONSTEXP (CONSTANT | 3) #define CONSTEXP (CONSTANT | 3)
The cpp manual deals with macros exhaustively. The gcc internals manual also The cpp manual deals with macros exhaustively. The gcc internals manual also
covers RTL which is used frequently with assembly language in the kernel. covers RTL which is used frequently with assembly language in the kernel.
@ -796,11 +799,11 @@ 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 For example, if you need to calculate the length of an array, take advantage
of the macro of the macro
#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
Similarly, if you need to calculate the size of some structure member, use Similarly, if you need to calculate the size of some structure member, use
#define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
There are also min() and max() macros that do strict type checking if you There are also min() and max() macros that do strict type checking if you
need them. Feel free to peruse that header file to see what else is already need them. Feel free to peruse that header file to see what else is already
@ -813,19 +816,19 @@ Some editors can interpret configuration information embedded in source files,
indicated with special markers. For example, emacs interprets lines marked indicated with special markers. For example, emacs interprets lines marked
like this: like this:
-*- mode: c -*- -*- mode: c -*-
Or like this: Or like this:
/* /*
Local Variables: Local Variables:
compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
End: End:
*/ */
Vim interprets markers that look like this: Vim interprets markers that look like this:
/* vim:set sw=8 noet */ /* vim:set sw=8 noet */
Do not include any of these in source files. People have their own personal Do not include any of these in source files. People have their own personal
editor configurations, and your source files should not override them. This editor configurations, and your source files should not override them. This
@ -902,9 +905,9 @@ 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 place a comment after the #endif on the same line, noting the conditional
expression used. For instance: expression used. For instance:
#ifdef CONFIG_SOMETHING #ifdef CONFIG_SOMETHING
... ...
#endif /* CONFIG_SOMETHING */ #endif /* CONFIG_SOMETHING */
Appendix I: References Appendix I: References