Coding Style
Hi ppl.. This is my first posting here and it will probably generate MORe flames than any previous posting but that isnt realy my intent,. The attached doccument is My answer to teh linux Coding Style doc as found in teh kernel sources bz2. It is done in parody of teh original doc and is meant to be laughed at as much as taken seriously.... no offense is intended towards the original author :)
Anyway, here goes -->
An answer to the Linux kernel coding style
This is a short document describing the preferred coding style for any sane project. Coding style is very personal, and I won't _force_ my views on anybody, but please at least consider the points made here.
First off, I'd suggest printing out a copy of the GNU coding standards, and NOT reading it. Burn them, it's a great symbolic gesture.
Anyway, here goes:
Chapter 1: Indentation
Tabs are 8 characters so NO tabs should be used in ANY source file what so ever. There are some silly people that insist on hitting the tab key when they should really be hitting the SPACE key (and for your info Linus PI is EXACTLY 3... ish :)
Rationale: Tabs force your code out to the right edge of the display leaving no room for comments. You don't need great big gaping spaces to delineate the start and end of a block, TWO spaces do this just fine.
Chapter 2: 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 choose one placement strategy over the other. The most ridiculous way is shown to us by the idiots Kernighan and Ritchie. I.E, to put the opening brace last on the line, and put the closing brace first, thusly:
if (x is true) {
we do y // original text failed to comment here
}Functions are not a special case simply because they can't be nested, they just happen to be the only thing K&R brace correctly. Anyway, nesting if, and & but loops is evil.
int function(int x)
{
body of function // correctly braced and commented :)
}Sane people all over the world have claimed that the K&R inconsistency is... well... inconsistent, and they are all right-thinking people who know that (a) K&R are _wrong_ and (b) K&R are very wrong.
Note that the closing brace is empty on a line of its own, _except_ in the cases where it is followed by a continuation of the same statement, ie a "while" in a do-statement or an "else" in an if-statement, like this:
do
{
body of do-loop // why do you insist on not commenting ?
} while (condition); // more on this later :)
Linus states that the placement of the first brace at the end of the first line keeps your code less vertical and thus saves you some space for comments. This commenting style just plane sucks, it fragments your source file creating all kinds of visual clutter making them impossible to read. New lines ARE A RENEWABLE resource, if they aren't then you need to buy more ram for your 8086 (or is it a z80 ?).
code code code
{
code code code
}
comment comment comment
code code code
comment comment
code
{
code
comment
code
}
...looks like shit....
code code code // comment comment comment
{
code code code // comment comment comment
}
code code code // comment comment
code // comment
{
code // comment
code // comment
}
...is much neater and also takes up allot less vertical space (thus blowing the argument Linus was making about braces eating up real estate). Yes we could shrink this further by bracing as per K&R but that would only serve to cram everything into an unreadable blob. SOME whitespace IS needed!!
One other thing. Allot of people neglect to brace a statement if it has a single line body. This is VERY bad, always brace your statements....
if (x = 1)
if (y = 2)
if (z = 3)
for (i = 1; i < 10; i++)
if ....
switch (foo)
........is really stupid. DON'T DO IT!
Chapter 3: Naming
Just read the document written by Linus, he is 100% correct here, Hungarian notation is not only brain damaged it is brain damaging. I know, I was forced to use it once and I am defiantly brain damaged :)
Oh... yea... that bit about function growth hormone imbalance syndrome was cute man :)
Chapter 4: Functions
Again, I point you in the direction of the original document.
I would however like to state that the C switch statement is evil and to be avoided at all costs. If you really need to use one for what ever reason then each case in that switch statement should be a CALL TO A FUNCTION! Never place the source for that function inline unless it is only ONE line of code (or at a push TWO lines). You can always make the compiler inline it for you!!!
Rationale.
switch(foo)
{
case 1:
... 500 lines of code
case 2: // at this point ALL context for the
... 500 lines of code // switch is lost. I.E. unreadable!
}
Even if its only 9 or 10 lines of code you STILL lose context on the switch statement. Poorly factored code is difficult to read. Very few C coders know how to factor their code well.
Chapter 5: Commenting
Comments are good, the more you comment your code the better. These comments are not for you, they are for the poor schmuck that has to deal with your scratching later. Never underestimate the stupidity of this guy, don't leave anything to chance. Never assume that HE will understand your logic simply because YOU do.
Rationale. If you have thunked about your code enough to comment it then you have thunked about it enough to CODE IT!
Chapter 6: You've made a mess of it
Just read what Linus wrote. Oh... Linus, its AN infinite number not A infinite number... and erm... what's emacs ??
Chapter 7: Configuration-files
Read what Linus wrote here, its a classic example of how to be totally inconsistent. Indentation should be 3 here but 2 there and 8 over there and 10 in this file but don't go over 29 in this file here...
DOH!
-----------------------------------------------------------------------
Ok.. So I'm a heretic... I admit it!
I have never really liked the C language, it seems to me that it has a habit of making ANY idiot think he/she can be a coder. C is an easy language to learn but to be a good C coder takes years of hard study and a TRUE artistic flair for programming. This means that 99% of all C code is JUNK code.
Before you all go running for your 1911 45 ACP's and 30-06's Linux is most defiantly in the 1% here, I just don't like the source format :P~
Comments and flames are welcome....
Mark I Manning IV [email protected]
-----------------------------------------------------------------------
Quoted 4 lines · Mark I Manning IV
Tabs are 8 characters so NO tabs should be used in ANY source file what so ever. There are some silly people that insist on hitting the tab key when they should really be hitting the SPACE key (and for your info Linus PI is EXACTLY 3... ish :)
If one is intelligent enough to use the TAB then everyone is free to indent and thereby display indent in their preferred spacing. Those of us that use 80c pages can shrink tabs down to a 2sp or 3sp while those of us that have 150c pages can expand them to 10sp if we so choose.
Silly person. Don't force your style on others by using spaces.
Quoted 3 lines
Rationale: Tabs force your code out to the right edge of the display leaving no room for comments. You don't need great big gaping spaces to delineate the start and end of a block, TWO spaces do this just fine.
Tabs are tabs for a reason, you can delineate tabular columns as you choose.
Quoted 9 lines
Note that the closing brace is empty on a line of its own, _except_ in the cases where it is followed by a continuation of the same statement, ie a "while" in a do-statement or an "else" in an if-statement, like this:
do
{
body of do-loop // why do you insist on not commenting ?
} while (condition); // more on this later :)
Looks a little inconsistent, why don't you put the opening brace on the same line as 'do'.
Quoted 6 lines
Linus states that the placement of the first brace at the end of the first line keeps your code less vertical and thus saves you some space for comments. This commenting style just plane sucks, it fragments your source file creating all kinds of visual clutter making them impossible to read. New lines ARE A RENEWABLE resource, if they aren't then you need to buy more ram for your 8086 (or is it a z80 ?).
Your style sucks. Trying to up your line count on your project?
Quoted 11 lines
code // comment
{
code // comment
code // comment
}...is much neater and also takes up allot less vertical space (thus blowing the argument Linus was making about braces eating up real estate). Yes we could shrink this further by bracing as per K&R but that would only serve to cram everything into an unreadable blob. SOME whitespace IS needed!!
Not when your code and your comment are required to span multiple lines. It is much easier to read a paragraph describing the following code than it is to read a very short snip on each line, often the code and comments out of sync with the line they are on due to lack of space.
Quoted 6 lines
One other thing. Allot of people neglect to brace a statement if it has a single line body. This is VERY bad, always brace your statements....
if (x = 1)
if (y = 2)
Quoted 7 lines
if (z = 3) for (i = 1; i < 10; i++) if .... switch (foo) ........is really stupid. DON'T DO IT!
No, it's really stupid to surround it with braces that aren't needed. The above is incredibly easy to read and incredibly easy to trace and debug.
Quoted 6 lines
I would however like to state that the C switch statement is evil and to be avoided at all costs. If you really need to use one for what ever reason then each case in that switch statement should be a CALL TO A FUNCTION! Never place the source for that function inline unless it is only ONE line of code (or at a push TWO lines). You can always make the compiler inline it for you!!!
I happen to love the switch function, it's incredibly useful. I don't know what your issue is if you can't keep a context of a dozen lines in a case block. I agree that 500 lines is too much, but limiting it to two, much less one, is brain damaged.
Quoted 3 lines
Even if its only 9 or 10 lines of code you STILL lose context on the switch statement. Poorly factored code is difficult to read. Very few C coders know how to factor their code well.
It seems you fit into this group.
Quoted 5 lines
Comments are good, the more you comment your code the better. These comments are not for you, they are for the poor schmuck that has to deal with your scratching later. Never underestimate the stupidity of this guy, don't leave anything to chance. Never assume that HE will understand your logic simply because YOU do.
In other words, DOCUMENT. Don't put very short snippets of vague reference on the end of a line of code. Don't clutter up your code with extraneous symbols such as braces. $does $perl $come $to $mind?
Quoted 4 lines
Ok.. So I'm a heretic... I admit it!
I have never really liked the C language, it seems to me that it has a habit of making ANY idiot think he/she can be a coder. C is an easy
That's perl IMO.
Quoted 6 lines
language to learn but to be a good C coder takes years of hard study and a TRUE artistic flair for programming. This means that 99% of all C code is JUNK code.
Before you all go running for your 1911 45 ACP's and 30-06's Linux is most defiantly in the 1% here, I just don't like the source format :P~
Then don't touch it. Nobody said you have to like someone else's code. Your values and figures are yours.
Quoted 1 line
Comments and flames are welcome....
Comments and flames happily provided and my reply is also in the don't read it if you don't like it category.
I like:
function()
{
...
}do {
/*
* iterate over the entire structure and update the values if their
* subtype is version 2
*/
...
} while();if (x==IV)<tab>// action is inverse vector
function();
if () {
clearly_named_function();
another_very_clearly_named_function();
}/*
* multi line comment
* ...
*/
I mix C and C++ comment style as is appropriate. It isn't going away and is standard in the preprocessor now.
It's my code :)
-d
--
There is a natural aristocracy among men. The grounds of this are virtue and talents. Thomas Jefferson The good thing about standards is that there are so many to choose from. Andrew S. Tanenbaum
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [email protected]
Please read the FAQ at http://www.tux.org/lkml/
Quoted 1 line
Tabs are 8 characters so NO tabs should be used in ANY source file what
...
Quoted 3 lines
Rationale: Tabs force your code out to the right edge of the display leaving no room for comments. You don't need great big gaping spaces to delineate the start and end of a block, TWO spaces do this just fine.
Correct, because adjustable tab width is a myth. The comments don't line up when you muck with tab width.
Quoted 4 lines
int function(int x)
{
body of function // correctly braced and commented :)
}1. put your head in a PET scanner
2. think about Pascal while the doctors observe
3. get radiation treatment to kill neurons infected with Pascal
Quoted 6 lines
Linus states that the placement of the first brace at the end of the first line keeps your code less vertical and thus saves you some space for comments. This commenting style just plane sucks, it fragments your source file creating all kinds of visual clutter making them impossible to read. New lines ARE A RENEWABLE resource, if they aren't then you need to buy more ram for your 8086 (or is it a z80 ?).
I get 30 to 60 lines on my monitors, but I want over 200 lines. Such a monitor would be at least $6000, assuming I could find one. (fuzzy text doesn't count)
Quoted 6 lines
One other thing. Allot of people neglect to brace a statement if it has a single line body. This is VERY bad, always brace your statements....
if (x = 1)
if (y = 2)
Quoted 7 lines
if (z = 3) for (i = 1; i < 10; i++) if .... switch (foo) ........is really stupid. DON'T DO IT!
Agreed, but braces are not the fix.
Quoted 3 lines
I would however like to state that the C switch statement is evil and to be avoided at all costs. If you really need to use one for what ever reason then each case in that switch statement should be a
The gcc computed goto extension is better, because it doesn't suffer the overhead of that stupid built-in default. We need __raw_switch to overcome this. If I leave out the default and pass in bogus values then I should get a crash. (this is about performance)
Quoted 5 lines
I have never really liked the C language, it seems to me that it has a habit of making ANY idiot think he/she can be a coder. C is an easy language to learn but to be a good C coder takes years of hard study and a TRUE artistic flair for programming. This means that 99% of all C code is JUNK code.
I'm still looking for a readable description of C99 aliasing rules and proper usage of "restrict". It is no wonder that schools are switching to Java.
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [email protected]
Please read the FAQ at http://www.tux.org/lkml/
Quoted 12 lines · David Ford
Quoted 12 lines
One other thing. Allot of people neglect to brace a statement if it has a single line body. This is VERY bad, always brace your statements....
if (x = 1)
if (y = 2)if (z = 3) for (i = 1; i < 10; i++) if .... switch (foo) .....
Quoted 4 lines
Quoted 1 line
...is really stupid. DON'T DO IT!
No, it's really stupid to surround it with braces that aren't needed. The above is incredibly easy to read and incredibly easy to trace and debug.
"really stupid" is probably too harsh in both cases...
Anyways, he has a point here: clarity. When doing late night debugging, your eyes are not going to be fooled as easily if the result of the condition is braced. Whether you consider it important is a personal taste, but it is also consistent with multi-line if statements, and when rapidly scanning code consistency is very useful.
The rest of it, I generally agree with, except I like perl. :o) But, just like working for a company, you follow the standards for the system you're working on.
John
P.S. What's wrong with perl? Very useful language IMHO.
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [email protected]
Please read the FAQ at http://www.tux.org/lkml/
In article <[email protected]>,
Quoted 8 lines · Albert D. Cahalan
Quoted 1 line
Tabs are 8 characters so NO tabs should be used in ANY source file what
...
Quoted 3 lines
Rationale: Tabs force your code out to the right edge of the display leaving no room for comments. You don't need great big gaping spaces to delineate the start and end of a block, TWO spaces do this just fine.
Correct, because adjustable tab width is a myth. The comments don't line up when you muck with tab width.
Read the Linux CodingStyle.
Tabs are 8 characters. They are NOT adjustable. Never have been, never will be. Anybody who thinks tabs are anything but 8 chars apart is just wrong. It's that simple.
And two spaces is not enough. If you write code that needs comments at the end of a line, your code is crap. It's that easy. There is _never_ a reason to comment a single line, and multi-line comments the the right of multi-line code to the left is a recipe for disaster. In short, you don't do comments to the right of code - you do them _before_ code.
Linus
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [email protected]
Please read the FAQ at http://www.tux.org/lkml/
[Don't take this too seriously, the author had asked for flames without meaning them, so this is the disclaimer ;-)]
Quoted 8 lines · Mark I Manning IV
found in teh kernel sources bz2. It is done in parody of teh original doc and is meant to be laughed at as much as taken seriously.... no offense is intended towards the original author :)
int function(int x) { body of function // correctly braced and commented :) }
So you claim // is a correct C comment? Poor guy :)
Quoted 3 lines
Sane people all over the world have claimed that the K&R inconsistency is... well... inconsistent, and they are all right-thinking people who know that (a) K&R are _wrong_ and (b) K&R are very wrong.
Hum, K&R were "somewhat involved" in C, but C has in the meanwhile become bigger than just K&R, so there.
Quoted 3 lines
Linus states that the placement of the first brace at the end of the first line keeps your code less vertical and thus saves you some space for comments. This commenting style just plane sucks,
Wow, airplanes. Who's bringing trains, ships and cars into Linux then? (Not the other way round, that'd be easy.)
Quoted 2 lines
I know, I was forced to use it once and I am defiantly brain damaged :)
What a confession.
Quoted 7 lines
Chapter 5: Commenting
Comments are good, the more you comment your code the better. These comments are not for you, they are for the poor schmuck that has to deal with your scratching later. Never underestimate the stupidity of this guy, don't leave anything to chance. Never assume that HE will understand your logic simply because YOU do.
Write readable code ;-)
Quoted 5 lines
I have never really liked the C language, it seems to me that it has a habit of making ANY idiot think he/she can be a coder. C is an easy language to learn but to be a good C coder takes years of hard study and a TRUE artistic flair for programming. This means that 99% of all C code is JUNK code.
Not sure about the percentage, but there are langauages that are more easily learned, and more easily abused, by people that have no clue what locking or semaphores are good for that then write data base applications for multiple simultaneous users.
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [email protected]
Please read the FAQ at http://www.tux.org/lkml/
Quoted 6 lines · Matthias Andree
Quoted 4 lines
int function(int x) { body of function // correctly braced and commented :) }So you claim // is a correct C comment? Poor guy :)
Current drafts of C9X implement // comments; virtually every halfway current C compiler I've used during the last years implements it.
Ralf
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [email protected]
Please read the FAQ at http://www.tux.org/lkml/
Quoted 10 lines · Ralf Baechle
Quoted 6 lines · Matthias Andree
Quoted 4 lines
int function(int x) { body of function // correctly braced and commented :) }So you claim // is a correct C comment? Poor guy :)
Quoted 8 lines
Current drafts of C9X implement // comments; virtually every halfway current C compiler I've used during the last years implements it.
Ralf
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [email protected]
Please read the FAQ at http://www.tux.org/lkml/
Any plane vanilla C compiler that doesnt support // as a coment is probably at least 10 years old :) His point wasnt that it wouldnt work, he was pointing out that this cmmenting style is frowned upon in C.
It is alot neater tho :P~
// even for multi line comments
// no visual clutter over there -->
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [email protected]
Please read the FAQ at http://www.tux.org/lkml/
Quoted 8 lines · Mark I Manning IV
Quoted 3 lines · Ralf Baechle
On Sun, Jan 21, 2001 at 03:00:05AM +0100, Matthias Andree wrote:
It is alot neater tho :P~
// even for multi line comments
// no visual clutter over there -->
/*
* I tend to find standard C comments easier to read. They stand out,
* especially for multiple lines (although I always try to put the :end:
* on a separate line for clarity).
*/
int function(int x)
{
/* Bleh. Comments take up space.
*/
function body;
}Regards,
Adrian
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [email protected]
Please read the FAQ at http://www.tux.org/lkml/
can we filter him out?
someone left the insane clinic door unlocked...
lynx
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [email protected]
Please read the FAQ at http://www.tux.org/lkml/