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>
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
index 6e0b7b9..e55accf 100644
--- a/Documentation/CodingStyle
+++ b/Documentation/CodingStyle
@@ -56,7 +56,6 @@
break;
}
-
Don't put multiple statements on a single line unless you have
something to hide:
@@ -156,25 +155,25 @@
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 @@
"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 @@
= + - < > * / % | & ^ <= >= == != ? :
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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