summaryrefslogtreecommitdiffstats
path: root/Documentation/CodingStyle
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2015-04-18 11:10:49 -0400
committerLinus Torvalds <torvalds@linux-foundation.org>2015-04-18 11:10:49 -0400
commitd6a24d0640d609138a4e40a4ce9fd9fe7859e24c (patch)
treeaa40fb7f5d03dc605634fb4030afd8798bd6bc0b /Documentation/CodingStyle
parent1f5014d6a77513fa7cefe30eb7791d5856c04384 (diff)
parent197175427a221fe3200f7727ea35e261727e7228 (diff)
downloadlinux-stable-d6a24d0640d609138a4e40a4ce9fd9fe7859e24c.tar.gz
linux-stable-d6a24d0640d609138a4e40a4ce9fd9fe7859e24c.tar.bz2
linux-stable-d6a24d0640d609138a4e40a4ce9fd9fe7859e24c.zip
Merge tag 'docs-for-linus' of git://git.lwn.net/linux-2.6
Pull documentation updates from Jonathan Corbet: "Numerous fixes, the overdue removal of the i2o docs, some new Chinese translations, and, hopefully, the README fix that will end the flow of identical patches to that file" * tag 'docs-for-linus' of git://git.lwn.net/linux-2.6: (34 commits) Documentation/memcg: update memcg/kmem status Documentation: blackfin: Makefile: Typo building issue Documentation/vm/pagemap.txt: correct location of page-types tool Documentation/memory-barriers.txt: typo fix doc: Add guest_nice column to example output of `cat /proc/stat' Documentation/kernel-parameters: Move "eagerfpu" to its right place Documentation: gpio: Update ACPI part of the document to mention _DSD docs/completion.txt: Various tweaks and corrections doc: completion: context, scope and language fixes Documentation:Update Documentation/zh_CN/arm64/memory.txt Documentation:Update Documentation/zh_CN/arm64/booting.txt Documentation: Chinese translation of arm64/legacy_instructions.txt DocBook media: fix broken EIA hyperlink Documentation: tweak the maintainers entry README: Change gzip/bzip2 to xz compression format README: Update version number reference doc:pci: Fix typo in Documentation/PCI Documentation: drm: Use '->' when describing access through pointers. Documentation: Remove mentioning of block barriers Documentation/email-clients.txt: Fix one grammar mistake, add extra info about TB ...
Diffstat (limited to 'Documentation/CodingStyle')
-rw-r--r--Documentation/CodingStyle149
1 files changed, 76 insertions, 73 deletions
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
index 4d4f06d47e06..f4b78eafd92a 100644
--- a/Documentation/CodingStyle
+++ b/Documentation/CodingStyle
@@ -13,7 +13,7 @@ and NOT read it. Burn them, it's a great symbolic gesture.
Anyway, here goes:
- Chapter 1: Indentation
+ Chapter 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!)
@@ -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;
-
- buffer = kmalloc(SIZE, GFP_KERNEL);
- if (!buffer)
- return -ENOMEM;
-
- if (condition1) {
- while (loop1) {
- ...
+ int fun(int a)
+ {
+ int result = 0;
+ char *buffer;
+
+ buffer = kmalloc(SIZE, GFP_KERNEL);
+ if (!buffer)
+ return -ENOMEM;
+
+ 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:".
@@ -503,9 +506,9 @@ 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)))
+ (column (c-langelem-2nd-pos c-syntactic-element))
+ (offset (- (1+ column) anchor))
+ (steps (floor offset c-basic-offset)))
(* (max steps 1)
c-basic-offset)))
@@ -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)
5) namespace collisions when defining local variables in macros resembling
functions:
@@ -809,11 +812,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
@@ -826,19 +829,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
@@ -915,9 +918,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