aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/CodingStyle126
1 files changed, 121 insertions, 5 deletions
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
index 29c18966b050..0ad6dcb5d45f 100644
--- a/Documentation/CodingStyle
+++ b/Documentation/CodingStyle
@@ -35,12 +35,37 @@ In short, 8-char indents make things easier to read, and have the added
35benefit of warning you when you're nesting your functions too deep. 35benefit of warning you when you're nesting your functions too deep.
36Heed that warning. 36Heed that warning.
37 37
38The preferred way to ease multiple indentation levels in a switch statement is
39to align the "switch" and its subordinate "case" labels in the same column
40instead of "double-indenting" the "case" labels. E.g.:
41
42 switch (suffix) {
43 case 'G':
44 case 'g':
45 mem <<= 30;
46 break;
47 case 'M':
48 case 'm':
49 mem <<= 20;
50 break;
51 case 'K':
52 case 'k':
53 mem <<= 10;
54 /* fall through */
55 default:
56 break;
57 }
58
59
38Don't put multiple statements on a single line unless you have 60Don't put multiple statements on a single line unless you have
39something to hide: 61something to hide:
40 62
41 if (condition) do_this; 63 if (condition) do_this;
42 do_something_everytime; 64 do_something_everytime;
43 65
66Don't put multiple assignments on a single line either. Kernel coding style
67is super simple. Avoid tricky expressions.
68
44Outside of comments, documentation and except in Kconfig, spaces are never 69Outside of comments, documentation and except in Kconfig, spaces are never
45used for indentation, and the above example is deliberately broken. 70used for indentation, and the above example is deliberately broken.
46 71
@@ -69,7 +94,7 @@ void fun(int a, int b, int c)
69 next_statement; 94 next_statement;
70} 95}
71 96
72 Chapter 3: Placing Braces 97 Chapter 3: Placing Braces and Spaces
73 98
74The other issue that always comes up in C styling is the placement of 99The other issue that always comes up in C styling is the placement of
75braces. Unlike the indent size, there are few technical reasons to 100braces. Unlike the indent size, there are few technical reasons to
@@ -81,6 +106,20 @@ brace last on the line, and put the closing brace first, thusly:
81 we do y 106 we do y
82 } 107 }
83 108
109This applies to all non-function statement blocks (if, switch, for,
110while, do). E.g.:
111
112 switch (action) {
113 case KOBJ_ADD:
114 return "add";
115 case KOBJ_REMOVE:
116 return "remove";
117 case KOBJ_CHANGE:
118 return "change";
119 default:
120 return NULL;
121 }
122
84However, there is one special case, namely functions: they have the 123However, there is one special case, namely functions: they have the
85opening brace at the beginning of the next line, thus: 124opening brace at the beginning of the next line, thus:
86 125
@@ -121,6 +160,49 @@ supply of new-lines on your screen is not a renewable resource (think
12125-line terminal screens here), you have more empty lines to put 16025-line terminal screens here), you have more empty lines to put
122comments on. 161comments on.
123 162
163 3.1: Spaces
164
165Linux kernel style for use of spaces depends (mostly) on
166function-versus-keyword usage. Use a space after (most) keywords. The
167notable exceptions are sizeof, typeof, alignof, and __attribute__, which look
168somewhat like functions (and are usually used with parentheses in Linux,
169although they are not required in the language, as in: "sizeof info" after
170"struct fileinfo info;" is declared).
171
172So use a space after these keywords:
173 if, switch, case, for, do, while
174but not with sizeof, typeof, alignof, or __attribute__. E.g.,
175 s = sizeof(struct file);
176
177Do not add spaces around (inside) parenthesized expressions. This example is
178*bad*:
179
180 s = sizeof( struct file );
181
182When declaring pointer data or a function that returns a pointer type, the
183preferred use of '*' is adjacent to the data name or function name and not
184adjacent to the type name. Examples:
185
186 char *linux_banner;
187 unsigned long long memparse(char *ptr, char **retptr);
188 char *match_strdup(substring_t *s);
189
190Use one space around (on each side of) most binary and ternary operators,
191such as any of these:
192
193 = + - < > * / % | & ^ <= >= == != ? :
194
195but no space after unary operators:
196 & * + - ~ ! sizeof typeof alignof __attribute__ defined
197
198no space before the postfix increment & decrement unary operators:
199 ++ --
200
201no space after the prefix increment & decrement unary operators:
202 ++ --
203
204and no space around the '.' and "->" structure member operators.
205
124 206
125 Chapter 4: Naming 207 Chapter 4: Naming
126 208
@@ -152,7 +234,7 @@ variable that is used to hold a temporary value.
152 234
153If you are afraid to mix up your local variable names, you have another 235If you are afraid to mix up your local variable names, you have another
154problem, which is called the function-growth-hormone-imbalance syndrome. 236problem, which is called the function-growth-hormone-imbalance syndrome.
155See next chapter. 237See chapter 6 (Functions).
156 238
157 239
158 Chapter 5: Typedefs 240 Chapter 5: Typedefs
@@ -258,6 +340,20 @@ generally easily keep track of about 7 different things, anything more
258and it gets confused. You know you're brilliant, but maybe you'd like 340and it gets confused. You know you're brilliant, but maybe you'd like
259to understand what you did 2 weeks from now. 341to understand what you did 2 weeks from now.
260 342
343In source files, separate functions with one blank line. If the function is
344exported, the EXPORT* macro for it should follow immediately after the closing
345function brace line. E.g.:
346
347int system_is_up(void)
348{
349 return system_state == SYSTEM_RUNNING;
350}
351EXPORT_SYMBOL(system_is_up);
352
353In function prototypes, include parameter names with their data types.
354Although this is not required by the C language, it is preferred in Linux
355because it is a simple way to add valuable information for the reader.
356
261 357
262 Chapter 7: Centralized exiting of functions 358 Chapter 7: Centralized exiting of functions
263 359
@@ -306,16 +402,36 @@ time to explain badly written code.
306Generally, you want your comments to tell WHAT your code does, not HOW. 402Generally, you want your comments to tell WHAT your code does, not HOW.
307Also, try to avoid putting comments inside a function body: if the 403Also, try to avoid putting comments inside a function body: if the
308function is so complex that you need to separately comment parts of it, 404function is so complex that you need to separately comment parts of it,
309you should probably go back to chapter 5 for a while. You can make 405you should probably go back to chapter 6 for a while. You can make
310small comments to note or warn about something particularly clever (or 406small comments to note or warn about something particularly clever (or
311ugly), but try to avoid excess. Instead, put the comments at the head 407ugly), but try to avoid excess. Instead, put the comments at the head
312of the function, telling people what it does, and possibly WHY it does 408of the function, telling people what it does, and possibly WHY it does
313it. 409it.
314 410
315When commenting the kernel API functions, please use the kerneldoc format. 411When commenting the kernel API functions, please use the kernel-doc format.
316See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc 412See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc
317for details. 413for details.
318 414
415Linux style for comments is the C89 "/* ... */" style.
416Don't use C99-style "// ..." comments.
417
418The preferred style for long (multi-line) comments is:
419
420 /*
421 * This is the preferred style for multi-line
422 * comments in the Linux kernel source code.
423 * Please use it consistently.
424 *
425 * Description: A column of asterisks on the left side,
426 * with beginning and ending almost-blank lines.
427 */
428
429It's also important to comment data, whether they are basic types or derived
430types. To this end, use just one data declaration per line (no commas for
431multiple data declarations). This leaves you room for a small comment on each
432item, explaining its use.
433
434
319 Chapter 9: You've made a mess of it 435 Chapter 9: You've made a mess of it
320 436
321That's OK, we all do. You've probably been told by your long-time Unix 437That's OK, we all do. You've probably been told by your long-time Unix
@@ -591,4 +707,4 @@ Kernel CodingStyle, by greg@kroah.com at OLS 2002:
591http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ 707http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
592 708
593-- 709--
594Last updated on 30 April 2006. 710Last updated on 2006-December-06.