Documentation/CodingStyle: improve text layout
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
Jonathan Corbet
parent
696156f03f
commit
09677e0ff8
@ -56,7 +56,6 @@ instead of "double-indenting" the "case" labels. E.g.:
|
||||
break;
|
||||
}
|
||||
|
||||
|
||||
Don't put multiple statements on a single line unless you have
|
||||
something to hide:
|
||||
|
||||
@ -156,25 +155,25 @@ comments on.
|
||||
|
||||
Do not unnecessarily use braces where a single statement will do.
|
||||
|
||||
if (condition)
|
||||
action();
|
||||
if (condition)
|
||||
action();
|
||||
|
||||
and
|
||||
|
||||
if (condition)
|
||||
do_this();
|
||||
else
|
||||
do_that();
|
||||
if (condition)
|
||||
do_this();
|
||||
else
|
||||
do_that();
|
||||
|
||||
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:
|
||||
|
||||
if (condition) {
|
||||
do_this();
|
||||
do_that();
|
||||
} else {
|
||||
otherwise();
|
||||
}
|
||||
if (condition) {
|
||||
do_this();
|
||||
do_that();
|
||||
} else {
|
||||
otherwise();
|
||||
}
|
||||
|
||||
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).
|
||||
|
||||
So use a space after these keywords:
|
||||
|
||||
if, switch, case, for, do, while
|
||||
|
||||
but not with sizeof, typeof, alignof, or __attribute__. E.g.,
|
||||
|
||||
s = sizeof(struct file);
|
||||
|
||||
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:
|
||||
|
||||
& * + - ~ ! sizeof typeof alignof __attribute__ defined
|
||||
|
||||
no space before the postfix increment & decrement unary operators:
|
||||
|
||||
++ --
|
||||
|
||||
no space after the prefix increment & decrement unary operators:
|
||||
|
||||
++ --
|
||||
|
||||
and no space around the '.' and "->" structure member operators.
|
||||
@ -268,13 +273,11 @@ See chapter 6 (Functions).
|
||||
Chapter 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
|
||||
|
||||
vps_t a;
|
||||
|
||||
in the source, what does it mean?
|
||||
|
||||
In contrast, if it says
|
||||
|
||||
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
|
||||
function brace line. E.g.:
|
||||
|
||||
int system_is_up(void)
|
||||
{
|
||||
return system_state == SYSTEM_RUNNING;
|
||||
}
|
||||
EXPORT_SYMBOL(system_is_up);
|
||||
int system_is_up(void)
|
||||
{
|
||||
return system_state == SYSTEM_RUNNING;
|
||||
}
|
||||
EXPORT_SYMBOL(system_is_up);
|
||||
|
||||
In function prototypes, include parameter names with their data types.
|
||||
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
|
||||
- saves the compiler work to optimize redundant code away ;)
|
||||
|
||||
int fun(int a)
|
||||
{
|
||||
int result = 0;
|
||||
char *buffer;
|
||||
int fun(int a)
|
||||
{
|
||||
int result = 0;
|
||||
char *buffer;
|
||||
|
||||
buffer = kmalloc(SIZE, GFP_KERNEL);
|
||||
if (!buffer)
|
||||
return -ENOMEM;
|
||||
buffer = kmalloc(SIZE, GFP_KERNEL);
|
||||
if (!buffer)
|
||||
return -ENOMEM;
|
||||
|
||||
if (condition1) {
|
||||
while (loop1) {
|
||||
...
|
||||
if (condition1) {
|
||||
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:
|
||||
|
||||
err:
|
||||
kfree(foo->bar);
|
||||
kfree(foo);
|
||||
return ret;
|
||||
err:
|
||||
kfree(foo->bar);
|
||||
kfree(foo);
|
||||
return ret;
|
||||
|
||||
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:".
|
||||
@ -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.
|
||||
|
||||
#define CONSTANT 0x12345
|
||||
#define CONSTANT 0x12345
|
||||
|
||||
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:
|
||||
|
||||
#define macrofun(a, b, c) \
|
||||
do { \
|
||||
if (a == 5) \
|
||||
do_this(b, c); \
|
||||
} while (0)
|
||||
#define macrofun(a, b, c) \
|
||||
do { \
|
||||
if (a == 5) \
|
||||
do_this(b, c); \
|
||||
} while (0)
|
||||
|
||||
Things to avoid when using macros:
|
||||
|
||||
1) macros that affect control flow:
|
||||
|
||||
#define FOO(x) \
|
||||
do { \
|
||||
if (blah(x) < 0) \
|
||||
return -EBUGGERED; \
|
||||
} while(0)
|
||||
#define FOO(x) \
|
||||
do { \
|
||||
if (blah(x) < 0) \
|
||||
return -EBUGGERED; \
|
||||
} while(0)
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
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
|
||||
macros using parameters.
|
||||
|
||||
#define CONSTANT 0x4000
|
||||
#define CONSTEXP (CONSTANT | 3)
|
||||
#define CONSTANT 0x4000
|
||||
#define CONSTEXP (CONSTANT | 3)
|
||||
|
||||
The cpp manual deals with macros exhaustively. The gcc internals manual also
|
||||
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
|
||||
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
|
||||
|
||||
#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
|
||||
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
|
||||
like this:
|
||||
|
||||
-*- mode: c -*-
|
||||
-*- mode: c -*-
|
||||
|
||||
Or like this:
|
||||
|
||||
/*
|
||||
Local Variables:
|
||||
compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
|
||||
End:
|
||||
*/
|
||||
/*
|
||||
Local Variables:
|
||||
compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
|
||||
End:
|
||||
*/
|
||||
|
||||
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
|
||||
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
|
||||
expression used. For instance:
|
||||
|
||||
#ifdef CONFIG_SOMETHING
|
||||
...
|
||||
#endif /* CONFIG_SOMETHING */
|
||||
#ifdef CONFIG_SOMETHING
|
||||
...
|
||||
#endif /* CONFIG_SOMETHING */
|
||||
|
||||
|
||||
Appendix I: References
|
||||
|
||||
Loading…
Reference in New Issue
Block a user