Messages in this thread Patch in this message | | | From | Michael Frank <> | Subject | PATCH, RFC: Version 3 of 2.6 Codingstyle | Date | Sat, 14 Feb 2004 09:44:32 +0800 |
| |
Changes:
Add reference to scripts/Lindent
Cleanups, spelling fixes and numbering of chapters.
Regards Michael
Patch against Version 2. Patch against in-kernel version attached
--- CodingStyle.mhf.orig.2 2004-02-13 16:42:07.000000000 +0800 +++ CodingStyle 2004-02-14 09:29:55.000000000 +0800 @@ -42,7 +42,7 @@ do_something_everytime; Outside of comments and except in Kconfig, spaces are never used for -indentation. +indentation, and the above example is deliberately broken. Don't leave whitespace at the end of lines. @@ -52,10 +52,12 @@ Coding style is all about readability and maintainability using commonly available tools. +The limit on the length of lines is 80 columns and this is a hard limit. + Statements longer than 80 columns will be broken into sensible chunks. -Descendant's are always shorter than the parent and are placed substantially -to the right. The same applies to function headers with a long argument list. -Long strings are as well broken into smaller strings. +Descendants are always substantially shorter than the parent and are placed +substantially to the right. The same applies to function headers with a long +argument list. Long strings are as well broken into smaller strings. void fun(int a, int b, int c) { @@ -67,8 +69,7 @@ next_statement; } - - Chapter : Placing Braces + Chapter 3: Placing Braces The other issue that always comes up in C styling is the placement of braces. Unlike the indent size, there are few technical reasons to @@ -121,7 +122,7 @@ comments on. - Chapter : Naming + Chapter 4: Naming C is a Spartan language, and so should your naming be. Unlike Modula-2 and Pascal programmers, C programmers do not use cute names like @@ -154,10 +155,10 @@ See next chapter. - Chapter : Functions + Chapter 5: Functions Functions should be short and sweet, and do just one thing. They should -fit on one or two screens full of text (the ISO/ANSI screen size is 80x24, +fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24, as we all know), and do one thing and do that well. The maximum length of a function is inversely proportional to the @@ -181,10 +182,10 @@ and it gets confused. You know you're brilliant, but maybe you'd like to understand what you did 2 weeks from now. -Centralized exiting of functions + Chapter 6: Centralized exiting of functions -Albeit deprecated by some people, the goto statement is used frequently -by compilers in form of the unconditional jump instruction. +Albeit deprecated by some people, the equivalent of the goto statement is +used frequently by compilers in form of the unconditional jump instruction. The goto statement comes in handy when a function exits from multiple locations and some common work such as cleanup has to be done. @@ -193,16 +194,17 @@ - unconditional statements are easier to understand and follow - nesting is reduced -- errors by not updating individual exit points when making modifications - are prevented +- errors by not updating individual exit points when making + modifications are prevented - saves the compiler work to optimize redundant code away ;) int fun(int ) { int result = 0; char *buffer = kmalloc(SIZE); + lock(something); - if (buffer == 0) { + if (buffer == NULL) { result = -1; goto out; } @@ -216,12 +218,13 @@ } ... out: - if (buffer) - kfree(buffer); + unlock(something); + if (buffer != NULL) // This test is not needed for kfree + kfree(buffer); // as kfree checks pointer return result; } - Chapter : Commenting + Chapter 7: Commenting Comments are good, but there is also a danger of over-commenting. NEVER try to explain HOW your code works in a comment: it's much better to @@ -238,7 +241,7 @@ it. - Chapter : You've made a mess of it + Chapter 8: You've made a mess of it That's OK, we all do. You've probably been told by your long-time Unix user helper that "GNU emacs" automatically formats the C sources for @@ -263,7 +266,7 @@ to add (setq auto-mode-alist (cons '("/usr/src/linux.*/.*\\.[ch]$" . linux-c-mode) - auto-mode-alist)) +auto-mode-alist)) to your .emacs file if you want to have linux-c-mode switched on automagically when you edit source files under /usr/src/linux. @@ -276,14 +279,15 @@ However, that's not too bad, because even the makers of GNU indent recognize the authority of K&R (the GNU people aren't evil, they are just severely misguided in this matter), so you just give indent the -options "-kr -i8" (stands for "K&R, 8 character indents"). +options "-kr -i8" (stands for "K&R, 8 character indents"), or use +"scripts/Lindent", which indents in the latest style. "indent" has a lot of options, and especially when it comes to comment -re-formatting you may want to take a look at the manual page. But +re-formatting you may want to take a look at the man page. But remember: "indent" is not a fix for bad programming. - Chapter : Configuration-files + Chapter 9: Configuration-files For configuration options (arch/xxx/Kconfig, and all the Kconfig files), somewhat different indentation is used. @@ -308,7 +312,7 @@ experimental options should be denoted (EXPERIMENTAL). - Chapter : Data structures + Chapter 10: Data structures Data structures that have visibility outside the single-threaded environment they are created and destroyed in should always have @@ -339,9 +343,9 @@ have a reference count on it, you almost certainly have a bug. - Chapter : Inlines, Enums and Macros + Chapter 11: Macros, Enums and Inline functions -Macros defining constants and values in enums are capitalized. +Names of macros defining constants and labels in enums are capitalized. #define CONSTANT 0x12345 @@ -358,10 +362,9 @@ do { \ if (a == 5) \ do_this(b,c); \ - \ } while (0) -Things to avoid when doing macros: +Things to avoid when using macros: 1) macros that affect control flow: @@ -374,7 +377,7 @@ 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 magic name: +2) macros that depend on having a local variable with a magic name: #define FOO(val) bar(index, val) @@ -382,16 +385,16 @@ code and it's prone to breakage from seemingly innocent changes. 3) macros with arguments that are used as l-values: FOO(x) = y; will -bite you if somebody e.g. turns FOO into inlined function. +bite you if somebody e.g. turns FOO into an inline function. -4) forgetting about sideeffects. Macros defining expressions must enclose the -expression in parenthesis. Note that this does not eliminate all side effects. +4) forgetting about side effects: macros defining expressions must enclose each +parameter and the expression in parentheses. #define CONSTEXP (CONSTANT | 3) #define MACWEXP(a,b) ((a) + (b)) - Chapter : Printing kernel messages + Chapter 12: Printing kernel messages Kernel developers like to be seen as literate. Do mind the spelling of kernel messages to make a good impression. Do not use crippled @@ -400,5 +403,3 @@ Kernel messages do not have to be terminated with a period. Printing numbers in parenthesis (%d) adds no value and should be avoided. - -
| |