lkml.org 
[lkml]   [2004]   [Feb]   [13]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
Patch in this message
/
From
SubjectPATCH, RFC: Version 3 of 2.6 Codingstyle
Date
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.
-
-
\
 
 \ /
  Last update: 2005-03-22 14:00    [W:0.136 / U:1.136 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site