linux-kernel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* Coding Style
@ 2001-01-19 17:59 Mark I Manning IV
  2001-01-20  0:09 ` David Ford
                   ` (3 more replies)
  0 siblings, 4 replies; 52+ messages in thread
From: Mark I Manning IV @ 2001-01-19 17:59 UTC (permalink / raw)
  To: linux-kernel

[-- Attachment #1: Type: text/plain, Size: 423 bytes --]

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  -->

[-- Attachment #2: CodingStyle --]
[-- Type: text/plain, Size: 6483 bytes --]



  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                  mark4@purplecoder.com

-----------------------------------------------------------------------    

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: Coding Style
  2001-01-19 17:59 Coding Style Mark I Manning IV
@ 2001-01-20  0:09 ` David Ford
  2001-01-20  1:26   ` John Cavan
  2001-01-20  0:46 ` Albert D. Cahalan
                   ` (2 subsequent siblings)
  3 siblings, 1 reply; 52+ messages in thread
From: David Ford @ 2001-01-20  0:09 UTC (permalink / raw)
  To: Mark I Manning IV; +Cc: linux-kernel

Mark I Manning IV wrote:

> 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.


> 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.


> 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'.



> 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?


> 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.


> 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!

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.


> 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.


> 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.


> 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?


> 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.


> 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.


> 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 majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: Coding Style
  2001-01-19 17:59 Coding Style Mark I Manning IV
  2001-01-20  0:09 ` David Ford
@ 2001-01-20  0:46 ` Albert D. Cahalan
  2001-01-20  5:34   ` Linus Torvalds
  2001-01-21  2:00 ` Matthias Andree
  2001-01-23 20:05 ` Boris Dragovic
  3 siblings, 1 reply; 52+ messages in thread
From: Albert D. Cahalan @ 2001-01-20  0:46 UTC (permalink / raw)
  To: Mark I Manning IV; +Cc: linux-kernel

> Tabs are 8 characters so NO tabs should be used in ANY source file what 
...
> 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.

>   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

> 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)

> 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!

Agreed, but braces are not the fix.

> 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)

> 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 majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: Coding Style
  2001-01-20  0:09 ` David Ford
@ 2001-01-20  1:26   ` John Cavan
  0 siblings, 0 replies; 52+ messages in thread
From: John Cavan @ 2001-01-20  1:26 UTC (permalink / raw)
  Cc: linux-kernel

David Ford wrote:
> > 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!
> 
> 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 majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: Coding Style
  2001-01-20  0:46 ` Albert D. Cahalan
@ 2001-01-20  5:34   ` Linus Torvalds
  0 siblings, 0 replies; 52+ messages in thread
From: Linus Torvalds @ 2001-01-20  5:34 UTC (permalink / raw)
  To: linux-kernel

In article <200101200046.f0K0kgj201065@saturn.cs.uml.edu>,
Albert D. Cahalan <acahalan@cs.uml.edu> wrote:
>> Tabs are 8 characters so NO tabs should be used in ANY source file what 
>...
>> 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 majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: Coding Style
  2001-01-19 17:59 Coding Style Mark I Manning IV
  2001-01-20  0:09 ` David Ford
  2001-01-20  0:46 ` Albert D. Cahalan
@ 2001-01-21  2:00 ` Matthias Andree
  2001-01-22  8:24   ` Ralf Baechle
  2001-01-23 20:05 ` Boris Dragovic
  3 siblings, 1 reply; 52+ messages in thread
From: Matthias Andree @ 2001-01-21  2:00 UTC (permalink / raw)
  To: linux-kernel

[Don't take this too seriously, the author had asked for flames without
meaning them, so this is the disclaimer ;-)]

On Fri, 19 Jan 2001, Mark I Manning IV wrote:

> 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 :)

> 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.

> 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.)

> I know, I was forced to use it once and I am defiantly brain 
> damaged :)

What a confession.

>     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 ;-)

> 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 majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: Coding Style
  2001-01-21  2:00 ` Matthias Andree
@ 2001-01-22  8:24   ` Ralf Baechle
  2001-01-22 22:28     ` Mark I Manning IV
  0 siblings, 1 reply; 52+ messages in thread
From: Ralf Baechle @ 2001-01-22  8:24 UTC (permalink / raw)
  To: linux-kernel

On Sun, Jan 21, 2001 at 03:00:05AM +0100, Matthias Andree wrote:

> >   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 majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: Coding Style
  2001-01-22  8:24   ` Ralf Baechle
@ 2001-01-22 22:28     ` Mark I Manning IV
  2001-01-23  3:56       ` adrian
  0 siblings, 1 reply; 52+ messages in thread
From: Mark I Manning IV @ 2001-01-22 22:28 UTC (permalink / raw)
  To: Ralf Baechle, linux-kernel

Ralf Baechle wrote:
> 
> On Sun, Jan 21, 2001 at 03:00:05AM +0100, Matthias Andree wrote:
> 
> > >   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 majordomo@vger.kernel.org
> 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 majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: Coding Style
  2001-01-22 22:28     ` Mark I Manning IV
@ 2001-01-23  3:56       ` adrian
  0 siblings, 0 replies; 52+ messages in thread
From: adrian @ 2001-01-23  3:56 UTC (permalink / raw)
  To: Mark I Manning IV; +Cc: Ralf Baechle, linux-kernel



On Mon, 22 Jan 2001, Mark I Manning IV wrote:

> Ralf Baechle wrote:
> >
> > 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 majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: Coding Style
  2001-01-19 17:59 Coding Style Mark I Manning IV
                   ` (2 preceding siblings ...)
  2001-01-21  2:00 ` Matthias Andree
@ 2001-01-23 20:05 ` Boris Dragovic
  3 siblings, 0 replies; 52+ messages in thread
From: Boris Dragovic @ 2001-01-23 20:05 UTC (permalink / raw)
  To: Mark I Manning IV; +Cc: linux-kernel


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 majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-16 15:49                               ` Linus Torvalds
@ 2007-06-19 14:05                                 ` Mark Lord
  0 siblings, 0 replies; 52+ messages in thread
From: Mark Lord @ 2007-06-19 14:05 UTC (permalink / raw)
  To: Linus Torvalds
  Cc: Jan Engelhardt, Cyrill Gorcunov, Kok, Auke, Randy Dunlap,
	Chris Friesen, dave young, Willy Tarreau, LKML

Linus Torvalds wrote:
>
> For example, if I get a patch for something that is a whole driver, I 
> generally think that while I *prefer* to see it follow the kernel coding 
> style, I also expect that the person who sends me the driver is the one 
> who is going to maintain it in the future, and thus his personal coding 
> style preferences will override any but the strongest objections.

As with most things Linux, it would be really nice if more people
here acted like our fearless Penguin leader.

But the reality is that perfectly good code is frequently rejected
(for rework) due to 81-character lines and even more trivial stylistic
differences, even (especially) in entirely new driver sources.

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-16 17:43                     ` Stefan Richter
@ 2007-06-16 18:22                       ` Cyrill Gorcunov
  0 siblings, 0 replies; 52+ messages in thread
From: Cyrill Gorcunov @ 2007-06-16 18:22 UTC (permalink / raw)
  To: Stefan Richter
  Cc: Kok, Auke, Chris Friesen, LKML, Randy Dunlap, Jan Engelhardt,
	dave young, Willy Tarreau, apw, jschopp

[Stefan Richter - Sat, Jun 16, 2007 at 07:43:12PM +0200]
| From: Stefan Richter <stefanr@s5r6.in-berlin.de>
| To: gorcunov@gmail.com
| CC: "Kok, Auke" <auke-jan.h.kok@intel.com>,
| 	Chris Friesen <cfriesen@nortel.com>,
| 	LKML <linux-kernel@vger.kernel.org>,
| 	Randy Dunlap <randy.dunlap@oracle.com>,
| 	Jan Engelhardt <jengelh@computergmbh.de>,
| 	dave young <hidave.darkstar@gmail.com>, Willy Tarreau <w@1wt.eu>,
| 	apw@shadowen.org, jschopp@austin.ibm.com
| Subject: Re: coding style
| Date: Sat, 16 Jun 2007 19:43:12 +0200
| 
| gorcunov@gmail.com wrote:
| > [Stefan Richter - Sat, Jun 16, 2007 at 03:07:43PM +0200]
| > | Cyrill Gorcunov wrote:
| > | > There sould be someting making strict rule over alignment (as it done
| > | > for the tabs size).
| > | 
| > | That's impracticable.  Alignment, as it serves readability, cannot be
| > | covered by a few strict rules.
| 
| > Yes, but C syntax (and grammar) is limited set. And alignmet I'm talking
| > about may cover the following statements only:
| > 
| > 1) Mathematical
| > 2) Logical
| > 3) Function's arguments
| 
| Sure, but we have sometimes long names and long ./-> dereference
| expressions.  Alignment of those after line wraps sometimes turns out
| better if 'taste' rather than a simple rule is applied.
| -- 
| Stefan Richter
| -=====-=-=== -==- =----
| http://arcgraph.de/sr/
| 

Of course you're absoulutely right!!! And that is why I've mentoined
that it would be _recommendations_ only in CodingStyle.

		Cyrill


^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-16 14:31                   ` gorcunov
@ 2007-06-16 17:43                     ` Stefan Richter
  2007-06-16 18:22                       ` Cyrill Gorcunov
  0 siblings, 1 reply; 52+ messages in thread
From: Stefan Richter @ 2007-06-16 17:43 UTC (permalink / raw)
  To: gorcunov
  Cc: Kok, Auke, Chris Friesen, LKML, Randy Dunlap, Jan Engelhardt,
	dave young, Willy Tarreau, apw, jschopp

gorcunov@gmail.com wrote:
> [Stefan Richter - Sat, Jun 16, 2007 at 03:07:43PM +0200]
> | Cyrill Gorcunov wrote:
> | > There sould be someting making strict rule over alignment (as it done
> | > for the tabs size).
> | 
> | That's impracticable.  Alignment, as it serves readability, cannot be
> | covered by a few strict rules.

> Yes, but C syntax (and grammar) is limited set. And alignmet I'm talking
> about may cover the following statements only:
> 
> 1) Mathematical
> 2) Logical
> 3) Function's arguments

Sure, but we have sometimes long names and long ./-> dereference
expressions.  Alignment of those after line wraps sometimes turns out
better if 'taste' rather than a simple rule is applied.
-- 
Stefan Richter
-=====-=-=== -==- =----
http://arcgraph.de/sr/

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-16  6:38                             ` Jan Engelhardt
  2007-06-16 12:40                               ` Stefan Richter
@ 2007-06-16 15:49                               ` Linus Torvalds
  2007-06-19 14:05                                 ` Mark Lord
  1 sibling, 1 reply; 52+ messages in thread
From: Linus Torvalds @ 2007-06-16 15:49 UTC (permalink / raw)
  To: Jan Engelhardt
  Cc: Cyrill Gorcunov, Kok, Auke, Randy Dunlap, Chris Friesen,
	dave young, Willy Tarreau, LKML



On Sat, 16 Jun 2007, Jan Engelhardt wrote:
> >
> >Heh. Actually, Linux maintainers have generally very consciously _avoided_ 
> >trying to "enforce" coding style issues.
> 
> Really? "it's not going to be merged unless you turn all uint32_t into
> u_int32_t" is a paraphrased variant of what I was told this month.

I suspect different maintainers are hung up on different things, so yes, 
certain things are more likely to carry red flags, and it also depends on 
the patch.

For example, if I get a patch for something that is a whole driver, I 
generally think that while I *prefer* to see it follow the kernel coding 
style, I also expect that the person who sends me the driver is the one 
who is going to maintain it in the future, and thus his personal coding 
style preferences will override any but the strongest objections.

(So if somebody sends me a FSF-style "tabs are two characters, and 
functions must be longer than 300 lines" mess, I generally would prefer to 
not take it at all, but for some really obscure driver I might not care).

In contrast, if a patch modifies code that somebody else really will end 
up touching in the future (maybe not "maintain", but maybe there is no 
single and obvious maintainer), it had better match the code around it.

So to take your particular example: For me, "uint32_t" is certainly better 
than "u_int32_t" (and there's seven times as many of the former as the 
latter in the kernel), but for code _I_ would touch, I'd actually prefer 
the Linux internal "__u32"/"u32", which have no question about what their 
user-space visibility is (ie "__u32" is *always* ok in a header file that 
is visible to user space).

But would I make it a huge issue? Not personally. So it will depend on the 
maintainer.

(Personally, I think the "small functions, no deep levels of indentation, 
and tabs are 8 characters wide" are the most important part by far. But I 
do actually end up complaining about function naming etc too).

		Linus

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-16 13:07                 ` Stefan Richter
@ 2007-06-16 14:31                   ` gorcunov
  2007-06-16 17:43                     ` Stefan Richter
  0 siblings, 1 reply; 52+ messages in thread
From: gorcunov @ 2007-06-16 14:31 UTC (permalink / raw)
  To: Stefan Richter
  Cc: Kok, Auke, Chris Friesen, LKML, Randy Dunlap, Jan Engelhardt,
	dave young, Willy Tarreau, apw, jschopp

[Stefan Richter - Sat, Jun 16, 2007 at 03:07:43PM +0200]
| Cyrill Gorcunov wrote:
| > There sould be someting making strict rule over alignment (as it done
| > for the tabs size).
| 
| That's impracticable.  Alignment, as it serves readability, cannot be
| covered by a few strict rules.
| -- 
| Stefan Richter
| -=====-=-=== -==- =----
| http://arcgraph.de/sr/
| 

Yes, but C syntax (and grammar) is limited set. And alignmet I'm talking
about may cover the following statements only:

1) Mathematical
2) Logical
3) Function's arguments

Btw, if I see header with definition like
	int foo(int);
instead of
	int foo(int arg);
it makes me nerve ;)

Of course that all concerned to statements being splitted to several lines.
And I think CodingStyle would have recommendations about it. But maybe
I'm just a moron ;)

		Cyrill


^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15  9:16       ` Jan Engelhardt
  2007-06-15 17:32         ` Cyrill Gorcunov
@ 2007-06-16 14:22         ` Clifford Wolf
  1 sibling, 0 replies; 52+ messages in thread
From: Clifford Wolf @ 2007-06-16 14:22 UTC (permalink / raw)
  To: Jan Engelhardt
  Cc: dave young, Kok, Auke, Willy Tarreau, Cyrill Gorcunov, LKML,
	Randy Dunlap

Hey,

On Fri, Jun 15, 2007 at 11:16:08AM +0200, Jan Engelhardt wrote:
> >> so which one is preferred for the kernel?
> 
> err = very_long_function_name(lots_of_arguments,
>                               less,
>                               less,
>                               less,
>                               less,
>                               even_more_arguments,
>                               more_of_this,
>                               more_of_that,
>                               more,
>                               more,
>                               more);
> 
> IMO, preferred:
> 
> err = very_long_function_name(lots_of_arguments, less, less, less, less,
>       even_more_arguments, more_of_this, more_of_that, more, more, more);

Looking at e.g. the fuction declarations in fs/namespace.c shows very well
that there seams to be no 'preferred in the kernel source' for this
question.

I presonally prefer indenting the continuation of a line with TWO
additional tabs so it is good to distinguish from a normally indented
command block. E.g.:

static int function_with_long_name(int and_many_arguments,
		int not_fitting_in_a_signle_line_anymore)
{
	if (and_many_arguments > not_fitting_in_a_signle_line_anymore &&
			not_fitting_in_a_signle_line_anymore > 0)
		and_many_arguments += not_fitting_in_a_signle_line_anymore;
	else
		not_fitting_in_a_signle_line_anymore *=
				not_fitting_in_a_signle_line_anymore;
	return and_many_arguments ^ not_fitting_in_a_signle_line_anymore;
}

maybe this won't win a design contest but it is a simple and non-ambiguous
coding style and afaics does not conflict with the CodingStyle document.

yours,
 - clifford

-- 
When your hammer is C++, everything begins to look like a thumb.

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15 18:22               ` Cyrill Gorcunov
@ 2007-06-16 13:07                 ` Stefan Richter
  2007-06-16 14:31                   ` gorcunov
  0 siblings, 1 reply; 52+ messages in thread
From: Stefan Richter @ 2007-06-16 13:07 UTC (permalink / raw)
  To: Cyrill Gorcunov
  Cc: Kok, Auke, Chris Friesen, LKML, Randy Dunlap, Jan Engelhardt,
	dave young, Willy Tarreau, apw, jschopp

Cyrill Gorcunov wrote:
> There sould be someting making strict rule over alignment (as it done
> for the tabs size).

That's impracticable.  Alignment, as it serves readability, cannot be
covered by a few strict rules.
-- 
Stefan Richter
-=====-=-=== -==- =----
http://arcgraph.de/sr/

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-16  6:38                             ` Jan Engelhardt
@ 2007-06-16 12:40                               ` Stefan Richter
  2007-06-16 15:49                               ` Linus Torvalds
  1 sibling, 0 replies; 52+ messages in thread
From: Stefan Richter @ 2007-06-16 12:40 UTC (permalink / raw)
  To: Jan Engelhardt
  Cc: Linus Torvalds, Cyrill Gorcunov, Kok, Auke, Randy Dunlap,
	Chris Friesen, dave young, Willy Tarreau, LKML

Jan Engelhardt wrote:
> On Jun 15 2007 13:39, Linus Torvalds wrote:
>> On Fri, 15 Jun 2007, Jan Engelhardt wrote:
>>> Linux maintainers will enforce \t "being"[1] 8, and will also enforce
>>> the 80-column limit[2].
>> Heh. Actually, Linux maintainers have generally very consciously _avoided_ 
>> trying to "enforce" coding style issues.
> 
> Really? "it's not going to be merged unless you turn all uint32_t into
> u_int32_t" is a paraphrased variant of what I was told this month.

Here is a 3rd variant:  I mostly enforce CodingStyle as far as I am
aware of deviations, but because I get so few contributions, I more and
more tend to adjust coding style on my own before commit, rather than to
bother the contributor.
-- 
Stefan Richter
-=====-=-=== -==- =----
http://arcgraph.de/sr/

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15 20:35                           ` Jan Engelhardt
@ 2007-06-16 12:30                             ` Stefan Richter
  0 siblings, 0 replies; 52+ messages in thread
From: Stefan Richter @ 2007-06-16 12:30 UTC (permalink / raw)
  To: Jan Engelhardt
  Cc: Linus Torvalds, Cyrill Gorcunov, Kok, Auke, Randy Dunlap,
	Chris Friesen, dave young, Willy Tarreau, LKML

Jan Engelhardt wrote:
> On Jun 15 2007 13:21, Linus Torvalds wrote:
>> On Fri, 15 Jun 2007, Cyrill Gorcunov wrote:
>>> | 
>>> | 	from CodingStyle:
>>> | 	Tabs are 8 characters,
[...]
>> I did indeed write that.
>>
>> Tabs are 8 characters in the kernel coding style.
> 
> That clarification ("in the kernel coding style") should end up in 
> CodingStyle. (Since tabs *are not* just 8 everywhere, which current 
> CodingStyle seems to imply. But maybe I'm just to blunt.)

linux/Documentation/CodingStyle is about... Linux kernel coding style.  :-)
-- 
Stefan Richter
-=====-=-=== -==- =----
http://arcgraph.de/sr/

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15 20:39                           ` Linus Torvalds
@ 2007-06-16  6:38                             ` Jan Engelhardt
  2007-06-16 12:40                               ` Stefan Richter
  2007-06-16 15:49                               ` Linus Torvalds
  0 siblings, 2 replies; 52+ messages in thread
From: Jan Engelhardt @ 2007-06-16  6:38 UTC (permalink / raw)
  To: Linus Torvalds
  Cc: Cyrill Gorcunov, Kok, Auke, Randy Dunlap, Chris Friesen,
	dave young, Willy Tarreau, LKML


On Jun 15 2007 13:39, Linus Torvalds wrote:
>On Fri, 15 Jun 2007, Jan Engelhardt wrote:
>> 
>> Linux maintainers will enforce \t "being"[1] 8, and will also enforce
>> the 80-column limit[2].
>
>Heh. Actually, Linux maintainers have generally very consciously _avoided_ 
>trying to "enforce" coding style issues.

Really? "it's not going to be merged unless you turn all uint32_t into
u_int32_t" is a paraphrased variant of what I was told this month.



	Jan
-- 

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15 19:18                 ` Cyrill Gorcunov
  2007-06-15 19:21                   ` Kok, Auke
@ 2007-06-15 22:10                   ` Randy Dunlap
  1 sibling, 0 replies; 52+ messages in thread
From: Randy Dunlap @ 2007-06-15 22:10 UTC (permalink / raw)
  To: Cyrill Gorcunov
  Cc: Jan Engelhardt, Chris Friesen, dave young, Kok, Auke,
	Willy Tarreau, LKML

On Fri, 15 Jun 2007 23:18:04 +0400 Cyrill Gorcunov wrote:

> [Jan Engelhardt - Fri, Jun 15, 2007 at 09:10:49PM +0200]
> | 
> | On Jun 15 2007 11:03, Randy Dunlap wrote:
> | >> 
> | >> "use tabs for indents and spaces for alignment"
> | >> 
> | >> If that means you need to use two dozen spaces, then so be it.
> | >
> | >I don't think that's what that rule means, but I didn't write it,
> | >so I'm not absolutely sure about it.
> | >
> | >but we know that tab stops are every 8th character, not 4 :)
> | 
> | Hardly.
> | 
> | 
> | 
> | 
> | 	Jan
> | -- 
> | 
> 
> Jan, as I see from CodingStyle:
> 
> 	"Tabs are 8 characters, and thus indentations are also 8 characters."
> 
> Actually it would be perfect to get strict rules also for math. and log.
> operators being splitted on several lines:

I disagree that CodingStyle should contain such strict rules for
line continuations.

> 	if (long_name_a || long_name_b ||
> 	    long_name_c)
> 
> 		or
> 
> 	if (long_name_a || long_name_b
> 	    || long_name_c)
> 	
> 	
> 	a = b + c + d + e +
> 	    f;
> 
> 		or
> 
> 	a = b + c + d + e
> 	    + f;


---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15 20:21                         ` Jan Engelhardt
@ 2007-06-15 20:39                           ` Linus Torvalds
  2007-06-16  6:38                             ` Jan Engelhardt
  0 siblings, 1 reply; 52+ messages in thread
From: Linus Torvalds @ 2007-06-15 20:39 UTC (permalink / raw)
  To: Jan Engelhardt
  Cc: Cyrill Gorcunov, Kok, Auke, Randy Dunlap, Chris Friesen,
	dave young, Willy Tarreau, LKML



On Fri, 15 Jun 2007, Jan Engelhardt wrote:
> 
> Linux maintainers will enforce \t "being"[1] 8, and will also enforce
> the 80-column limit[2].

Heh. Actually, Linux maintainers have generally very consciously _avoided_ 
trying to "enforce" coding style issues.

We encourage. Sometimes people actually end up running "lindent" on code 
and enforce the rules through that, but that is actually fairly rare, and 
most of the time that happens only when somebody decides to tackle some 
subsystem that hasn't effectively been maintained in a while, and in order 
to do cleanups, the person needs to just make it readable first.

Is that the _onbly_ case when we do that? No. There's the occasional 
Lindent run done randomly, usually brought on by something _really_ 
atrocious, but I would say that generally we try to keep code churn due to 
_just_ coding style issues to a minimum.

I do sometimes end up not taking *new* code if it is really really ugly. 
So it definitely happens. But...

			Linus


^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15 20:21                         ` Linus Torvalds
@ 2007-06-15 20:35                           ` Jan Engelhardt
  2007-06-16 12:30                             ` Stefan Richter
  0 siblings, 1 reply; 52+ messages in thread
From: Jan Engelhardt @ 2007-06-15 20:35 UTC (permalink / raw)
  To: Linus Torvalds
  Cc: Cyrill Gorcunov, Kok, Auke, Randy Dunlap, Chris Friesen,
	dave young, Willy Tarreau, LKML



On Jun 15 2007 13:21, Linus Torvalds wrote:
>On Fri, 15 Jun 2007, Cyrill Gorcunov wrote:
>> | 
>> | 	from CodingStyle:
>> | 	Tabs are 8 characters, and thus indentations are also 8
>> | 	characters.  There are heretic movements that try to make
>> | 	indentations 4 (or even 2!) characters deep, and that is akin
>> | 	to trying to define the value of PI to be 3.
>> | 
>> | Linus (did he wrote that part?) and the heretics both can have their fun 
>> | without impacting each other. If we wanted to force the user to have 
>> | exactly 8 screen blanks, we should use spaces throughout.
>
>I did indeed write that.
>
>Tabs are 8 characters in the kernel coding style.

That clarification ("in the kernel coding style") should end up in 
CodingStyle. (Since tabs *are not* just 8 everywhere, which current 
CodingStyle seems to imply. But maybe I'm just to blunt.)

>And yes, I also wrote the other quote:
>
>> 	Now, some people will claim that having 8-character indentations makes
>> 	the code move too far to the right, and makes it hard to read on a
>> 	80-character terminal screen.  The answer to that is that if you need
>> 	more than 3 levels of indentation, you're screwed anyway, and should fix
>> 	your program.
>
>In the kernel, we try to split functions up, and perhaps use inline 
>functions etc, and really really avoid deep indentation.

This rule is also very helpful outside the kernel.



	Jan
-- 
(And IMHO, GNU code, e.g. coreutils, is the best counter-example.)

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15 19:45                       ` Kok, Auke
  2007-06-15 19:49                         ` Cyrill Gorcunov
@ 2007-06-15 20:28                         ` Jan Engelhardt
  1 sibling, 0 replies; 52+ messages in thread
From: Jan Engelhardt @ 2007-06-15 20:28 UTC (permalink / raw)
  To: Kok, Auke
  Cc: Cyrill Gorcunov, Randy Dunlap, Chris Friesen, dave young,
	Willy Tarreau, LKML


On Jun 15 2007 12:45, Kok, Auke wrote:
>> 
>> Well tabs should _never_ be assumed to be 8, and in this regard, as I see it,
>> CodingStyle has a bug. Tabs are there so that the user can set their width
>> according to _their_ taste, simply so that both sides,
>> 
>>  from CodingStyle:
>>  Tabs are 8 characters, and thus indentations are also 8
>>  characters.  There are heretic movements that try to make
>>  indentations 4 (or even 2!) characters deep, and that is akin
>>  to trying to define the value of PI to be 3.
>
> again, this is about *indentation* and not about alignment
>
>> Linus (did he wrote that part?) and the heretics both can have their fun
>> without impacting each other. If we wanted to force the user to have exactly
>> 8 screen blanks, we should use spaces throughout.
>
> Linus was friendly enough to give us permission to use tabs. He forces tabs for
> indentation, but leaves it up to everyone else to (1) set their editor to show
> tabs as 2 or 4 or whatever, and (2) use spaces for alignment.
>
> the bottom line here is that we encourage everyone to use tabs=8, and allow
> some degree of freedom for some people to vary this *AND* have decent looking
> alignment for *EVERYONE* by allowing them to use spaces for alignment.

I'll just say "+1", because that's what I meant.


Blame university for mathematical pickiness:

>>  Tabs are 8 characters, and thus indentations are also 8

is wrong ;-)   --

 *  Tabs _are_ 1 character (use a hex editor and see) and
 *  Tabs _are not always displayed_ as "8 characters"
    [there exists a user for which \t != 8] [not me though]
 *  Tabs _are displayed_ as _much characters as the user specifies_.

(CodingStyle could need a clarification.)



	Jan
-- 

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15 19:41                       ` Cyrill Gorcunov
  2007-06-15 20:21                         ` Linus Torvalds
@ 2007-06-15 20:21                         ` Jan Engelhardt
  2007-06-15 20:39                           ` Linus Torvalds
  1 sibling, 1 reply; 52+ messages in thread
From: Jan Engelhardt @ 2007-06-15 20:21 UTC (permalink / raw)
  To: Cyrill Gorcunov
  Cc: Kok, Auke, Randy Dunlap, Chris Friesen, dave young,
	Willy Tarreau, LKML, Linus Torvalds


On Jun 15 2007 23:41, Cyrill Gorcunov wrote:
>
>Dunno who wrote that part :(. Jan, look:
>
>	Now, some people will claim that having 8-character indentations makes
>	the code move too far to the right, and makes it hard to read on a
>	80-character terminal screen.  The answer to that is that if you need
>	more than 3 levels of indentation, you're screwed anyway, and should fix
>	your program.
>
>your opinion? Is it a bug too? Don't get me wrong I'm just trying to clarify
>coding style.

Linux maintainers will enforce \t "being"[1] 8, and will also enforce
the 80-column limit[2].

(Assuming maintainer != developer)

To [1]: There is actually no substance in how wide a tab is. The developer
may set a tab width of 4, the maintainer may have his tab width set to 12,
and the end user to 6. As far as I interpret CodingStyle, it reads:

	Use \ts for indent, spaces for align, and make sure your code
	fits into 80 columns when the tab width would be 8.
	(You can test that by adjusting your tab width temporarily)

To [2]: There's always code slipping in that disobeys this ;-)



	Jan
-- 

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15 19:41                       ` Cyrill Gorcunov
@ 2007-06-15 20:21                         ` Linus Torvalds
  2007-06-15 20:35                           ` Jan Engelhardt
  2007-06-15 20:21                         ` Jan Engelhardt
  1 sibling, 1 reply; 52+ messages in thread
From: Linus Torvalds @ 2007-06-15 20:21 UTC (permalink / raw)
  To: Cyrill Gorcunov
  Cc: Jan Engelhardt, Kok, Auke, Randy Dunlap, Chris Friesen,
	dave young, Willy Tarreau, LKML



On Fri, 15 Jun 2007, Cyrill Gorcunov wrote:
> | 
> | 	from CodingStyle:
> | 	Tabs are 8 characters, and thus indentations are also 8
> | 	characters.  There are heretic movements that try to make
> | 	indentations 4 (or even 2!) characters deep, and that is akin
> | 	to trying to define the value of PI to be 3.
> | 
> | Linus (did he wrote that part?) and the heretics both can have their fun 
> | without impacting each other. If we wanted to force the user to have 
> | exactly 8 screen blanks, we should use spaces throughout.

I did indeed write that.

Tabs are 8 characters in the kernel coding style.

And yes, I also wrote the other quote:

> Dunno who wrote that part :(. Jan, look:
> 
> 	Now, some people will claim that having 8-character indentations makes
> 	the code move too far to the right, and makes it hard to read on a
> 	80-character terminal screen.  The answer to that is that if you need
> 	more than 3 levels of indentation, you're screwed anyway, and should fix
> 	your program.

and I think that's in many ways even more important than the 8-character 
tab, because deep indentation is unreadable even if you *can* fit it on a 
single line.

In the kernel, we try to split functions up, and perhaps use inline 
functions etc, and really really avoid deep indentation.

		Linus

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15 19:45                       ` Kok, Auke
@ 2007-06-15 19:49                         ` Cyrill Gorcunov
  2007-06-15 20:28                         ` Jan Engelhardt
  1 sibling, 0 replies; 52+ messages in thread
From: Cyrill Gorcunov @ 2007-06-15 19:49 UTC (permalink / raw)
  To: Kok, Auke
  Cc: Jan Engelhardt, Cyrill Gorcunov, Randy Dunlap, Chris Friesen,
	dave young, Willy Tarreau, LKML

[Kok, Auke - Fri, Jun 15, 2007 at 12:45:23PM -0700]
| Jan Engelhardt wrote:
| >On Jun 15 2007 12:21, Kok, Auke wrote:
| >>Cyrill Gorcunov wrote:
| >>>[Jan Engelhardt - Fri, Jun 15, 2007 at 09:10:49PM +0200]
| >>>| On Jun 15 2007 11:03, Randy Dunlap wrote:
| >>>| > > 
| >>>| > > "use tabs for indents and spaces for alignment"
| >>>| > > 
| >>>| > > If that means you need to use two dozen spaces, then so be it.
| >>>| >
| >>>| >I don't think that's what that rule means, but I didn't write it,
| >>>| >so I'm not absolutely sure about it.
| >>>| >
| >>>| >but we know that tab stops are every 8th character, not 4 :)
| >>>| 
| >>>| Hardly.
| >>>| 
| >>>Jan, as I see from CodingStyle:
| >>>
| >>> "Tabs are 8 characters, and thus indentations are also 8 characters."
| >>>
| >>>Actually it would be perfect to get strict rules also for math. and log.
| >>>operators being splitted on several lines:
| >>this doesn't say anything about alignment, which was his point :)
| >
| >Well tabs should _never_ be assumed to be 8, and in this regard, as I 
| >see it, CodingStyle has a bug. Tabs are there so that the user can set 
| >their width according to _their_ taste, simply so that both sides,
| >
| >	from CodingStyle:
| >	Tabs are 8 characters, and thus indentations are also 8
| >	characters.  There are heretic movements that try to make
| >	indentations 4 (or even 2!) characters deep, and that is akin
| >	to trying to define the value of PI to be 3.
| 
| again, this is about *indentation* and not about alignment
| 
| >Linus (did he wrote that part?) and the heretics both can have their fun 
| >without impacting each other. If we wanted to force the user to have 
| >exactly 8 screen blanks, we should use spaces throughout.
| 
| Linus was friendly enough to give us permission to use tabs. He forces tabs 
| for indentation, but leaves it up to everyone else to (1) set their editor 
| to show tabs as 2 or 4 or whatever, and (2) use spaces for alignment.
| 
| the bottom line here is that we encourage everyone to use tabs=8, and allow 
| some degree of freedom for some people to vary this *AND* have decent 
| looking alignment for *EVERYONE* by allowing them to use spaces for 
| alignment.
| 
| Nothing in the codingstyle document confirms or denies this, so I will 
| assume that it is _allowed_ to use spaces for alignment.
		^^^^^^^^^^^^^^^
Actually that is exactly what I was expecting to see. Thanks a lot.

| 
| the checkpatch.pl script doesn't disallow spaces for alignment - it is dumb 
| enough to complain about more than 8 spaces for alignment.
| 
| That is and was the whole point... and worth the addition to CodingStyle 
| for me
| 
| 
| Auke
| 


		Cyrill


^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15 19:31                     ` Jan Engelhardt
  2007-06-15 19:41                       ` Cyrill Gorcunov
@ 2007-06-15 19:45                       ` Kok, Auke
  2007-06-15 19:49                         ` Cyrill Gorcunov
  2007-06-15 20:28                         ` Jan Engelhardt
  1 sibling, 2 replies; 52+ messages in thread
From: Kok, Auke @ 2007-06-15 19:45 UTC (permalink / raw)
  To: Jan Engelhardt
  Cc: Cyrill Gorcunov, Randy Dunlap, Chris Friesen, dave young,
	Willy Tarreau, LKML

Jan Engelhardt wrote:
> On Jun 15 2007 12:21, Kok, Auke wrote:
>> Cyrill Gorcunov wrote:
>>> [Jan Engelhardt - Fri, Jun 15, 2007 at 09:10:49PM +0200]
>>> | On Jun 15 2007 11:03, Randy Dunlap wrote:
>>> | > > 
>>> | > > "use tabs for indents and spaces for alignment"
>>> | > > 
>>> | > > If that means you need to use two dozen spaces, then so be it.
>>> | >
>>> | >I don't think that's what that rule means, but I didn't write it,
>>> | >so I'm not absolutely sure about it.
>>> | >
>>> | >but we know that tab stops are every 8th character, not 4 :)
>>> | 
>>> | Hardly.
>>> | 
>>> Jan, as I see from CodingStyle:
>>>
>>>  "Tabs are 8 characters, and thus indentations are also 8 characters."
>>>
>>> Actually it would be perfect to get strict rules also for math. and log.
>>> operators being splitted on several lines:
>> this doesn't say anything about alignment, which was his point :)
> 
> Well tabs should _never_ be assumed to be 8, and in this regard, as I 
> see it, CodingStyle has a bug. Tabs are there so that the user can set 
> their width according to _their_ taste, simply so that both sides,
> 
> 	from CodingStyle:
> 	Tabs are 8 characters, and thus indentations are also 8
> 	characters.  There are heretic movements that try to make
> 	indentations 4 (or even 2!) characters deep, and that is akin
> 	to trying to define the value of PI to be 3.

again, this is about *indentation* and not about alignment

> Linus (did he wrote that part?) and the heretics both can have their fun 
> without impacting each other. If we wanted to force the user to have 
> exactly 8 screen blanks, we should use spaces throughout.

Linus was friendly enough to give us permission to use tabs. He forces tabs for 
indentation, but leaves it up to everyone else to (1) set their editor to show 
tabs as 2 or 4 or whatever, and (2) use spaces for alignment.

the bottom line here is that we encourage everyone to use tabs=8, and allow some 
degree of freedom for some people to vary this *AND* have decent looking 
alignment for *EVERYONE* by allowing them to use spaces for alignment.

Nothing in the codingstyle document confirms or denies this, so I will assume 
that it is _allowed_ to use spaces for alignment.

the checkpatch.pl script doesn't disallow spaces for alignment - it is dumb 
enough to complain about more than 8 spaces for alignment.

That is and was the whole point... and worth the addition to CodingStyle for me


Auke

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15 19:31                     ` Jan Engelhardt
@ 2007-06-15 19:41                       ` Cyrill Gorcunov
  2007-06-15 20:21                         ` Linus Torvalds
  2007-06-15 20:21                         ` Jan Engelhardt
  2007-06-15 19:45                       ` Kok, Auke
  1 sibling, 2 replies; 52+ messages in thread
From: Cyrill Gorcunov @ 2007-06-15 19:41 UTC (permalink / raw)
  To: Jan Engelhardt
  Cc: Kok, Auke, Cyrill Gorcunov, Randy Dunlap, Chris Friesen,
	dave young, Willy Tarreau, LKML, Linus Torvalds

[Jan Engelhardt - Fri, Jun 15, 2007 at 09:31:27PM +0200]
| 
| On Jun 15 2007 12:21, Kok, Auke wrote:
| > Cyrill Gorcunov wrote:
| >> [Jan Engelhardt - Fri, Jun 15, 2007 at 09:10:49PM +0200]
| >> | On Jun 15 2007 11:03, Randy Dunlap wrote:
| >> | > > 
| >> | > > "use tabs for indents and spaces for alignment"
| >> | > > 
| >> | > > If that means you need to use two dozen spaces, then so be it.
| >> | >
| >> | >I don't think that's what that rule means, but I didn't write it,
| >> | >so I'm not absolutely sure about it.
| >> | >
| >> | >but we know that tab stops are every 8th character, not 4 :)
| >> | 
| >> | Hardly.
| >> | 
| >> Jan, as I see from CodingStyle:
| >> 
| >>  "Tabs are 8 characters, and thus indentations are also 8 characters."
| >> 
| >> Actually it would be perfect to get strict rules also for math. and log.
| >> operators being splitted on several lines:
| >
| > this doesn't say anything about alignment, which was his point :)
| 
| Well tabs should _never_ be assumed to be 8, and in this regard, as I 
| see it, CodingStyle has a bug. Tabs are there so that the user can set 
| their width according to _their_ taste, simply so that both sides,
| 
| 	from CodingStyle:
| 	Tabs are 8 characters, and thus indentations are also 8
| 	characters.  There are heretic movements that try to make
| 	indentations 4 (or even 2!) characters deep, and that is akin
| 	to trying to define the value of PI to be 3.
| 
| Linus (did he wrote that part?) and the heretics both can have their fun 
| without impacting each other. If we wanted to force the user to have 
| exactly 8 screen blanks, we should use spaces throughout.
| 
| (And BTW,  int pi = 3.141592 _is_ going to be 3 ;-) and floating point 
| is mostly an agreed no-go in kernel anyway, even if it's supported.)
| 
| 
| 
| 	Jan
| -- 
| 

Dunno who wrote that part :(. Jan, look:

	Now, some people will claim that having 8-character indentations makes
	the code move too far to the right, and makes it hard to read on a
	80-character terminal screen.  The answer to that is that if you need
	more than 3 levels of indentation, you're screwed anyway, and should fix
	your program.

your opinion? Is it a bug too? Don't get me wrong I'm just trying to clarify
coding style.

		Cyrill


^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15 19:21                   ` Kok, Auke
  2007-06-15 19:29                     ` Cyrill Gorcunov
@ 2007-06-15 19:31                     ` Jan Engelhardt
  2007-06-15 19:41                       ` Cyrill Gorcunov
  2007-06-15 19:45                       ` Kok, Auke
  1 sibling, 2 replies; 52+ messages in thread
From: Jan Engelhardt @ 2007-06-15 19:31 UTC (permalink / raw)
  To: Kok, Auke
  Cc: Cyrill Gorcunov, Randy Dunlap, Chris Friesen, dave young,
	Willy Tarreau, LKML


On Jun 15 2007 12:21, Kok, Auke wrote:
> Cyrill Gorcunov wrote:
>> [Jan Engelhardt - Fri, Jun 15, 2007 at 09:10:49PM +0200]
>> | On Jun 15 2007 11:03, Randy Dunlap wrote:
>> | > > 
>> | > > "use tabs for indents and spaces for alignment"
>> | > > 
>> | > > If that means you need to use two dozen spaces, then so be it.
>> | >
>> | >I don't think that's what that rule means, but I didn't write it,
>> | >so I'm not absolutely sure about it.
>> | >
>> | >but we know that tab stops are every 8th character, not 4 :)
>> | 
>> | Hardly.
>> | 
>> Jan, as I see from CodingStyle:
>> 
>>  "Tabs are 8 characters, and thus indentations are also 8 characters."
>> 
>> Actually it would be perfect to get strict rules also for math. and log.
>> operators being splitted on several lines:
>
> this doesn't say anything about alignment, which was his point :)

Well tabs should _never_ be assumed to be 8, and in this regard, as I 
see it, CodingStyle has a bug. Tabs are there so that the user can set 
their width according to _their_ taste, simply so that both sides,

	from CodingStyle:
	Tabs are 8 characters, and thus indentations are also 8
	characters.  There are heretic movements that try to make
	indentations 4 (or even 2!) characters deep, and that is akin
	to trying to define the value of PI to be 3.

Linus (did he wrote that part?) and the heretics both can have their fun 
without impacting each other. If we wanted to force the user to have 
exactly 8 screen blanks, we should use spaces throughout.

(And BTW,  int pi = 3.141592 _is_ going to be 3 ;-) and floating point 
is mostly an agreed no-go in kernel anyway, even if it's supported.)



	Jan
-- 

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15 19:21                   ` Kok, Auke
@ 2007-06-15 19:29                     ` Cyrill Gorcunov
  2007-06-15 19:31                     ` Jan Engelhardt
  1 sibling, 0 replies; 52+ messages in thread
From: Cyrill Gorcunov @ 2007-06-15 19:29 UTC (permalink / raw)
  To: Kok, Auke
  Cc: Cyrill Gorcunov, Jan Engelhardt, Randy Dunlap, Chris Friesen,
	dave young, Willy Tarreau, LKML

[Kok, Auke - Fri, Jun 15, 2007 at 12:21:23PM -0700]
| Cyrill Gorcunov wrote:
| >[Jan Engelhardt - Fri, Jun 15, 2007 at 09:10:49PM +0200]
| >| 
| >| On Jun 15 2007 11:03, Randy Dunlap wrote:
| >| >> 
| >| >> "use tabs for indents and spaces for alignment"
| >| >> 
| >| >> If that means you need to use two dozen spaces, then so be it.
| >| >
| >| >I don't think that's what that rule means, but I didn't write it,
| >| >so I'm not absolutely sure about it.
| >| >
| >| >but we know that tab stops are every 8th character, not 4 :)
| >| 
| >| Hardly.
| >| 
| >| 
| >| 
| >| 
| >| 	Jan
| >| -- 
| >| 
| >
| >Jan, as I see from CodingStyle:
| >
| >	"Tabs are 8 characters, and thus indentations are also 8 characters."
| >
| >Actually it would be perfect to get strict rules also for math. and log.
| >operators being splitted on several lines:
| 
| this doesn't say anything about alignment, which was his point :)
| 
| Auke
| 

Yep... ;)

		Cyrill


^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15 19:18                 ` Cyrill Gorcunov
@ 2007-06-15 19:21                   ` Kok, Auke
  2007-06-15 19:29                     ` Cyrill Gorcunov
  2007-06-15 19:31                     ` Jan Engelhardt
  2007-06-15 22:10                   ` Randy Dunlap
  1 sibling, 2 replies; 52+ messages in thread
From: Kok, Auke @ 2007-06-15 19:21 UTC (permalink / raw)
  To: Cyrill Gorcunov
  Cc: Jan Engelhardt, Randy Dunlap, Chris Friesen, dave young,
	Willy Tarreau, LKML

Cyrill Gorcunov wrote:
> [Jan Engelhardt - Fri, Jun 15, 2007 at 09:10:49PM +0200]
> | 
> | On Jun 15 2007 11:03, Randy Dunlap wrote:
> | >> 
> | >> "use tabs for indents and spaces for alignment"
> | >> 
> | >> If that means you need to use two dozen spaces, then so be it.
> | >
> | >I don't think that's what that rule means, but I didn't write it,
> | >so I'm not absolutely sure about it.
> | >
> | >but we know that tab stops are every 8th character, not 4 :)
> | 
> | Hardly.
> | 
> | 
> | 
> | 
> | 	Jan
> | -- 
> | 
> 
> Jan, as I see from CodingStyle:
> 
> 	"Tabs are 8 characters, and thus indentations are also 8 characters."
> 
> Actually it would be perfect to get strict rules also for math. and log.
> operators being splitted on several lines:

this doesn't say anything about alignment, which was his point :)

Auke

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15 19:10               ` Jan Engelhardt
@ 2007-06-15 19:18                 ` Cyrill Gorcunov
  2007-06-15 19:21                   ` Kok, Auke
  2007-06-15 22:10                   ` Randy Dunlap
  0 siblings, 2 replies; 52+ messages in thread
From: Cyrill Gorcunov @ 2007-06-15 19:18 UTC (permalink / raw)
  To: Jan Engelhardt
  Cc: Randy Dunlap, Chris Friesen, Cyrill Gorcunov, dave young, Kok,
	Auke, Willy Tarreau, LKML

[Jan Engelhardt - Fri, Jun 15, 2007 at 09:10:49PM +0200]
| 
| On Jun 15 2007 11:03, Randy Dunlap wrote:
| >> 
| >> "use tabs for indents and spaces for alignment"
| >> 
| >> If that means you need to use two dozen spaces, then so be it.
| >
| >I don't think that's what that rule means, but I didn't write it,
| >so I'm not absolutely sure about it.
| >
| >but we know that tab stops are every 8th character, not 4 :)
| 
| Hardly.
| 
| 
| 
| 
| 	Jan
| -- 
| 

Jan, as I see from CodingStyle:

	"Tabs are 8 characters, and thus indentations are also 8 characters."

Actually it would be perfect to get strict rules also for math. and log.
operators being splitted on several lines:

	if (long_name_a || long_name_b ||
	    long_name_c)

		or

	if (long_name_a || long_name_b
	    || long_name_c)
	
	
	a = b + c + d + e +
	    f;

		or

	a = b + c + d + e
	    + f;


		Cyrill


^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15 18:03             ` Randy Dunlap
@ 2007-06-15 19:10               ` Jan Engelhardt
  2007-06-15 19:18                 ` Cyrill Gorcunov
  0 siblings, 1 reply; 52+ messages in thread
From: Jan Engelhardt @ 2007-06-15 19:10 UTC (permalink / raw)
  To: Randy Dunlap
  Cc: Chris Friesen, Cyrill Gorcunov, dave young, Kok, Auke,
	Willy Tarreau, LKML


On Jun 15 2007 11:03, Randy Dunlap wrote:
>> 
>> "use tabs for indents and spaces for alignment"
>> 
>> If that means you need to use two dozen spaces, then so be it.
>
>I don't think that's what that rule means, but I didn't write it,
>so I'm not absolutely sure about it.
>
>but we know that tab stops are every 8th character, not 4 :)

Hardly.




	Jan
-- 

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15 18:05             ` Kok, Auke
@ 2007-06-15 18:22               ` Cyrill Gorcunov
  2007-06-16 13:07                 ` Stefan Richter
  0 siblings, 1 reply; 52+ messages in thread
From: Cyrill Gorcunov @ 2007-06-15 18:22 UTC (permalink / raw)
  To: Kok, Auke
  Cc: Chris Friesen, LKML, Randy Dunlap, Jan Engelhardt, dave young,
	Willy Tarreau, apw, jschopp

[Kok, Auke - Fri, Jun 15, 2007 at 11:05:07AM -0700]
| Chris Friesen wrote:
| >Consider two people, one with tabs as 8 characters and one with tabs as 
| >4 characters.  If person A aligns using a tab plus a space (giving 9 
| >characters), then the alignmnet will be all screwed up for person B (who 
| >will see 5 characters of alignment).
| >
| >The only rule that works (setting aside bad tools) is:
| >
| >"use tabs for indents and spaces for alignment"
| >
| >If that means you need to use two dozen spaces, then so be it.
| 
| it would be awesome if the checkpatch.pl script could distinguish between 
| indentation and alignment space usage - this is going to cause major 
| confusion with patch submitters.
| 
| I personally think that the sentence
| 
|   "use tabs for indents and spaces for alignment"

Absoulutely agreed with you! There sould be someting making strict rule
over alignment (as it done for the tabs size).

| 
| should also be in the CodingStyle document to avoid confusion.
| 
| Auke
| 

		Cyrill


^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15 17:54           ` Chris Friesen
  2007-06-15 18:03             ` Randy Dunlap
@ 2007-06-15 18:05             ` Kok, Auke
  2007-06-15 18:22               ` Cyrill Gorcunov
  1 sibling, 1 reply; 52+ messages in thread
From: Kok, Auke @ 2007-06-15 18:05 UTC (permalink / raw)
  To: Chris Friesen, LKML, Randy Dunlap
  Cc: Cyrill Gorcunov, Jan Engelhardt, dave young, Willy Tarreau, apw, jschopp

Chris Friesen wrote:
> Consider two people, one with tabs as 8 characters and one with tabs as 
> 4 characters.  If person A aligns using a tab plus a space (giving 9 
> characters), then the alignmnet will be all screwed up for person B (who 
> will see 5 characters of alignment).
> 
> The only rule that works (setting aside bad tools) is:
> 
> "use tabs for indents and spaces for alignment"
> 
> If that means you need to use two dozen spaces, then so be it.

it would be awesome if the checkpatch.pl script could distinguish between 
indentation and alignment space usage - this is going to cause major confusion 
with patch submitters.

I personally think that the sentence

   "use tabs for indents and spaces for alignment"

should also be in the CodingStyle document to avoid confusion.

Auke

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15 17:54           ` Chris Friesen
@ 2007-06-15 18:03             ` Randy Dunlap
  2007-06-15 19:10               ` Jan Engelhardt
  2007-06-15 18:05             ` Kok, Auke
  1 sibling, 1 reply; 52+ messages in thread
From: Randy Dunlap @ 2007-06-15 18:03 UTC (permalink / raw)
  To: Chris Friesen
  Cc: Cyrill Gorcunov, Jan Engelhardt, dave young, Kok, Auke,
	Willy Tarreau, LKML

On Fri, 15 Jun 2007 11:54:14 -0600 Chris Friesen wrote:

> Cyrill Gorcunov wrote:
> 
> > Thanks to all of you for answering. Actually I was concerning about function
> > arguments' alignment (on separated lines) not about indentation. So as I see
> > it's a question of bent ;) And a simple rule exist - use tabs for indents
> > and spaces for alignment (when amount of spaces are < 8).
> 
> That rule doesn't actually work though, an is imposed by tools limitations.
> 
> Consider two people, one with tabs as 8 characters and one with tabs as 
> 4 characters.  If person A aligns using a tab plus a space (giving 9 
> characters), then the alignmnet will be all screwed up for person B (who 
> will see 5 characters of alignment).
> 
> The only rule that works (setting aside bad tools) is:
> 
> "use tabs for indents and spaces for alignment"
> 
> If that means you need to use two dozen spaces, then so be it.

I don't think that's what that rule means, but I didn't write it,
so I'm not absolutely sure about it.

but we know that tab stops are every 8th character, not 4 :)

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15 17:32         ` Cyrill Gorcunov
@ 2007-06-15 17:54           ` Chris Friesen
  2007-06-15 18:03             ` Randy Dunlap
  2007-06-15 18:05             ` Kok, Auke
  0 siblings, 2 replies; 52+ messages in thread
From: Chris Friesen @ 2007-06-15 17:54 UTC (permalink / raw)
  To: Cyrill Gorcunov
  Cc: Jan Engelhardt, dave young, Kok, Auke, Willy Tarreau, LKML, Randy Dunlap

Cyrill Gorcunov wrote:

> Thanks to all of you for answering. Actually I was concerning about function
> arguments' alignment (on separated lines) not about indentation. So as I see
> it's a question of bent ;) And a simple rule exist - use tabs for indents
> and spaces for alignment (when amount of spaces are < 8).

That rule doesn't actually work though, an is imposed by tools limitations.

Consider two people, one with tabs as 8 characters and one with tabs as 
4 characters.  If person A aligns using a tab plus a space (giving 9 
characters), then the alignmnet will be all screwed up for person B (who 
will see 5 characters of alignment).

The only rule that works (setting aside bad tools) is:

"use tabs for indents and spaces for alignment"

If that means you need to use two dozen spaces, then so be it.

Chris

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15  9:16       ` Jan Engelhardt
@ 2007-06-15 17:32         ` Cyrill Gorcunov
  2007-06-15 17:54           ` Chris Friesen
  2007-06-16 14:22         ` Clifford Wolf
  1 sibling, 1 reply; 52+ messages in thread
From: Cyrill Gorcunov @ 2007-06-15 17:32 UTC (permalink / raw)
  To: Jan Engelhardt; +Cc: dave young, Kok, Auke, Willy Tarreau, LKML, Randy Dunlap

[Jan Engelhardt - Fri, Jun 15, 2007 at 11:16:08AM +0200]
| 
| 
| Cyrill wrote:
| >>      err = foo(arg_a, arg_b, arg_c,
| >>                arg_d);
|   1    23        4
| 
| (note: monospace font needed)
| 
| 
| Dave wrote:
| > The Documentation/CodingStyle says:
| >
| > Outside of comments, documentation and except in Kconfig, spaces are never
| > used for indentation, and the above example is deliberately broken.
| 
| Everything is right. The indent only goes from "1" to "2" [see above], 
| "3" to "4" is called
| 
| 	Cyrill wrote:
| 	>> [spaces only for] alignment
| 
| Cyrill wrote:
| >> so which one is preferred for the kernel?
| 
| err = very_long_function_name(lots_of_arguments,
|                               less,
|                               less,
|                               less,
|                               less,
|                               even_more_arguments,
|                               more_of_this,
|                               more_of_that,
|                               more,
|                               more,
|                               more);
| 
| IMO, preferred:
| 
| err = very_long_function_name(lots_of_arguments, less, less, less, less,
|       even_more_arguments, more_of_this, more_of_that, more, more, more);
| 
| YMMV.
| 
| 
| 	Jan
| -- 
| 

Thanks to all of you for answering. Actually I was concerning about function
arguments' alignment (on separated lines) not about indentation. So as I see
it's a question of bent ;) And a simple rule exist - use tabs for indents
and spaces for alignment (when amount of spaces are < 8).

		Cyrill


^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15  6:38     ` dave young
  2007-06-15  6:47       ` debian developer
@ 2007-06-15  9:16       ` Jan Engelhardt
  2007-06-15 17:32         ` Cyrill Gorcunov
  2007-06-16 14:22         ` Clifford Wolf
  1 sibling, 2 replies; 52+ messages in thread
From: Jan Engelhardt @ 2007-06-15  9:16 UTC (permalink / raw)
  To: dave young; +Cc: Kok, Auke, Willy Tarreau, Cyrill Gorcunov, LKML, Randy Dunlap



Cyrill wrote:
>>      err = foo(arg_a, arg_b, arg_c,
>>                arg_d);
  1    23        4

(note: monospace font needed)


Dave wrote:
> The Documentation/CodingStyle says:
>
> Outside of comments, documentation and except in Kconfig, spaces are never
> used for indentation, and the above example is deliberately broken.

Everything is right. The indent only goes from "1" to "2" [see above], 
"3" to "4" is called

	Cyrill wrote:
	>> [spaces only for] alignment

Cyrill wrote:
>> so which one is preferred for the kernel?

err = very_long_function_name(lots_of_arguments,
                              less,
                              less,
                              less,
                              less,
                              even_more_arguments,
                              more_of_this,
                              more_of_that,
                              more,
                              more,
                              more);

IMO, preferred:

err = very_long_function_name(lots_of_arguments, less, less, less, less,
      even_more_arguments, more_of_this, more_of_that, more, more, more);

YMMV.


	Jan
-- 

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15  5:09   ` Kok, Auke
  2007-06-15  6:38     ` dave young
@ 2007-06-15  8:56     ` Krzysztof Halasa
  1 sibling, 0 replies; 52+ messages in thread
From: Krzysztof Halasa @ 2007-06-15  8:56 UTC (permalink / raw)
  To: Kok, Auke; +Cc: Willy Tarreau, Cyrill Gorcunov, LKML, Randy Dunlap

"Kok, Auke" <auke-jan.h.kok@intel.com> writes:

> the current "checkpatch.pl" script rejects this notion and requires
> that you use tabs whenever you can (you can still align code within
> the length of one tab).

Tool deficiency.
-- 
Krzysztof Halasa

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15  6:47       ` debian developer
@ 2007-06-15  6:54         ` dave young
  0 siblings, 0 replies; 52+ messages in thread
From: dave young @ 2007-06-15  6:54 UTC (permalink / raw)
  To: debian developer
  Cc: Kok, Auke, Willy Tarreau, Cyrill Gorcunov, LKML, Randy Dunlap

Hi,

2007/6/15, debian developer <debiandev@gmail.com>:

> And *Please* do not top-post!
> I know gmail directly goes to the top while replying, but think of
> other mail clients out there.
>
Yes, it go to the top directly, and tabs of pasted code will be
converted to white spaces, so I need use mutt to post patches.

Regards
dave

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15  6:38     ` dave young
@ 2007-06-15  6:47       ` debian developer
  2007-06-15  6:54         ` dave young
  2007-06-15  9:16       ` Jan Engelhardt
  1 sibling, 1 reply; 52+ messages in thread
From: debian developer @ 2007-06-15  6:47 UTC (permalink / raw)
  To: dave young; +Cc: Kok, Auke, Willy Tarreau, Cyrill Gorcunov, LKML, Randy Dunlap

On 6/15/07, dave young <hidave.darkstar@gmail.com> wrote:
> Hi,
> The Documentation/CodingStyle says:
>
> Outside of comments, documentation and except in Kconfig, spaces are never
> used for indentation, and the above example is deliberately broken.
>
> Regards
> dave
>
> 2007/6/15, Kok, Auke <auke-jan.h.kok@intel.com>:
> > Willy Tarreau wrote:
> > > On Thu, Jun 14, 2007 at 10:48:36PM +0400, Cyrill Gorcunov wrote:
> > >> Hi to all,
> > >>
> > >> a simple question the answer to witch I didn't find in CodingStyle.
> > >> Look for a code snip:
> > >>
> > >>      err = foo(arg_a, arg_b, arg_c,
> > >>              arg_d);
> > >>
> > >> the second line contains 'd' arg aligned with tabs only
> > >> but it could be rewritten with more elegant style (by adding
> > >> a few spaces) like this
> > >>
> > >>      err = foo(arg_a, arg_b, arg_c,
> > >>                arg_d);
> > >>
> > >> so which one is preferred for the kernel?
> > >
> > > There is no "preferred", just one good and one bad :-)
> > >
> > > Ideally, you should use tabs only for indentation, and spaces only for
> > > alignment. Keep in mind that there are people using different tab sizes
> > > and that your tabs should not make it harder for them to read your code.
> > > In your example above, you should use tabs from left up to "err", then
> > > spaces to go from "err" to "arg_d".
> > >
> > > However, we know that some editors such as emacs are stupid in this regard,
> > > because they fill with tabs then complete with spaces, so it's not always
> > > easy.
> >
> > the current "checkpatch.pl" script rejects this notion and requires that you use
> > tabs whenever you can (you can still align code within the length of one tab).
> >
> > Since in the example part (2) above there are 9 spaces needed to go from err to
> > arg_d, it complains if you had used 9 spaces here. It only allows you to use
> > tabs + n spaces (where n < 8)
> >
> > I personally prefer spaces, but the checkpatch.pl script does not agree, much to
> > my dismay :(
> >
> >
> > Auke
> > -
> > To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
> > the body of a message to majordomo@vger.kernel.org
> > More majordomo info at  http://vger.kernel.org/majordomo-info.html
> > Please read the FAQ at  http://www.tux.org/lkml/
> >
> -
> To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> Please read the FAQ at  http://www.tux.org/lkml/
>
And *Please* do not top-post!
I know gmail directly goes to the top while replying, but think of
other mail clients out there.

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15  5:09   ` Kok, Auke
@ 2007-06-15  6:38     ` dave young
  2007-06-15  6:47       ` debian developer
  2007-06-15  9:16       ` Jan Engelhardt
  2007-06-15  8:56     ` Krzysztof Halasa
  1 sibling, 2 replies; 52+ messages in thread
From: dave young @ 2007-06-15  6:38 UTC (permalink / raw)
  To: Kok, Auke; +Cc: Willy Tarreau, Cyrill Gorcunov, LKML, Randy Dunlap

Hi,
The Documentation/CodingStyle says:

Outside of comments, documentation and except in Kconfig, spaces are never
used for indentation, and the above example is deliberately broken.

Regards
dave

2007/6/15, Kok, Auke <auke-jan.h.kok@intel.com>:
> Willy Tarreau wrote:
> > On Thu, Jun 14, 2007 at 10:48:36PM +0400, Cyrill Gorcunov wrote:
> >> Hi to all,
> >>
> >> a simple question the answer to witch I didn't find in CodingStyle.
> >> Look for a code snip:
> >>
> >>      err = foo(arg_a, arg_b, arg_c,
> >>              arg_d);
> >>
> >> the second line contains 'd' arg aligned with tabs only
> >> but it could be rewritten with more elegant style (by adding
> >> a few spaces) like this
> >>
> >>      err = foo(arg_a, arg_b, arg_c,
> >>                arg_d);
> >>
> >> so which one is preferred for the kernel?
> >
> > There is no "preferred", just one good and one bad :-)
> >
> > Ideally, you should use tabs only for indentation, and spaces only for
> > alignment. Keep in mind that there are people using different tab sizes
> > and that your tabs should not make it harder for them to read your code.
> > In your example above, you should use tabs from left up to "err", then
> > spaces to go from "err" to "arg_d".
> >
> > However, we know that some editors such as emacs are stupid in this regard,
> > because they fill with tabs then complete with spaces, so it's not always
> > easy.
>
> the current "checkpatch.pl" script rejects this notion and requires that you use
> tabs whenever you can (you can still align code within the length of one tab).
>
> Since in the example part (2) above there are 9 spaces needed to go from err to
> arg_d, it complains if you had used 9 spaces here. It only allows you to use
> tabs + n spaces (where n < 8)
>
> I personally prefer spaces, but the checkpatch.pl script does not agree, much to
> my dismay :(
>
>
> Auke
> -
> To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> Please read the FAQ at  http://www.tux.org/lkml/
>

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-15  4:51 ` Willy Tarreau
@ 2007-06-15  5:09   ` Kok, Auke
  2007-06-15  6:38     ` dave young
  2007-06-15  8:56     ` Krzysztof Halasa
  0 siblings, 2 replies; 52+ messages in thread
From: Kok, Auke @ 2007-06-15  5:09 UTC (permalink / raw)
  To: Willy Tarreau; +Cc: Cyrill Gorcunov, LKML, Randy Dunlap

Willy Tarreau wrote:
> On Thu, Jun 14, 2007 at 10:48:36PM +0400, Cyrill Gorcunov wrote:
>> Hi to all,
>>
>> a simple question the answer to witch I didn't find in CodingStyle.
>> Look for a code snip:
>>
>> 	err = foo(arg_a, arg_b, arg_c,
>> 		arg_d);
>>
>> the second line contains 'd' arg aligned with tabs only
>> but it could be rewritten with more elegant style (by adding
>> a few spaces) like this
>>
>> 	err = foo(arg_a, arg_b, arg_c,
>> 		  arg_d);
>>
>> so which one is preferred for the kernel?
> 
> There is no "preferred", just one good and one bad :-)
> 
> Ideally, you should use tabs only for indentation, and spaces only for
> alignment. Keep in mind that there are people using different tab sizes
> and that your tabs should not make it harder for them to read your code.
> In your example above, you should use tabs from left up to "err", then
> spaces to go from "err" to "arg_d".
> 
> However, we know that some editors such as emacs are stupid in this regard,
> because they fill with tabs then complete with spaces, so it's not always
> easy.

the current "checkpatch.pl" script rejects this notion and requires that you use 
tabs whenever you can (you can still align code within the length of one tab).

Since in the example part (2) above there are 9 spaces needed to go from err to 
arg_d, it complains if you had used 9 spaces here. It only allows you to use 
tabs + n spaces (where n < 8)

I personally prefer spaces, but the checkpatch.pl script does not agree, much to 
my dismay :(


Auke

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: coding style
  2007-06-14 18:48 coding style Cyrill Gorcunov
@ 2007-06-15  4:51 ` Willy Tarreau
  2007-06-15  5:09   ` Kok, Auke
  0 siblings, 1 reply; 52+ messages in thread
From: Willy Tarreau @ 2007-06-15  4:51 UTC (permalink / raw)
  To: Cyrill Gorcunov; +Cc: LKML

On Thu, Jun 14, 2007 at 10:48:36PM +0400, Cyrill Gorcunov wrote:
> 
> Hi to all,
> 
> a simple question the answer to witch I didn't find in CodingStyle.
> Look for a code snip:
> 
> 	err = foo(arg_a, arg_b, arg_c,
> 		arg_d);
> 
> the second line contains 'd' arg aligned with tabs only
> but it could be rewritten with more elegant style (by adding
> a few spaces) like this
> 
> 	err = foo(arg_a, arg_b, arg_c,
> 		  arg_d);
> 
> so which one is preferred for the kernel?

There is no "preferred", just one good and one bad :-)

Ideally, you should use tabs only for indentation, and spaces only for
alignment. Keep in mind that there are people using different tab sizes
and that your tabs should not make it harder for them to read your code.
In your example above, you should use tabs from left up to "err", then
spaces to go from "err" to "arg_d".

However, we know that some editors such as emacs are stupid in this regard,
because they fill with tabs then complete with spaces, so it's not always
easy.

Regards,
Willy


^ permalink raw reply	[flat|nested] 52+ messages in thread

* coding style
@ 2007-06-14 18:48 Cyrill Gorcunov
  2007-06-15  4:51 ` Willy Tarreau
  0 siblings, 1 reply; 52+ messages in thread
From: Cyrill Gorcunov @ 2007-06-14 18:48 UTC (permalink / raw)
  To: LKML


Hi to all,

a simple question the answer to witch I didn't find in CodingStyle.
Look for a code snip:

	err = foo(arg_a, arg_b, arg_c,
		arg_d);

the second line contains 'd' arg aligned with tabs only
but it could be rewritten with more elegant style (by adding
a few spaces) like this

	err = foo(arg_a, arg_b, arg_c,
		  arg_d);

so which one is preferred for the kernel?

		Cyrill


^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: Coding Style
  2001-01-23 15:07 Jonathan Earle
@ 2001-01-24  3:23 ` john slee
  0 siblings, 0 replies; 52+ messages in thread
From: john slee @ 2001-01-24  3:23 UTC (permalink / raw)
  To: Jonathan Earle; +Cc: linux-kernel

On Tue, Jan 23, 2001 at 10:07:10AM -0500, Jonathan Earle wrote:
> > /*
> >  * 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).
> >  */
> 
> I like this style for multiple line comments, but prefer the '//' for single
> liners.  Two less characters to type after all.  :)

and potentially no end of weird problems if you have mac users editing
your code...  suddenly a compiler may ignore the rest of a file starting
at a given // or # comment, and you'll find its caused by their
different linebreaks.  had this problem with php.  havent seen it with C
yet.  does gcc handle non-correct^H^H^H^H^H^H^Hunix linebreaks now?  it
didnt when i used djgpp all those years ago.

// are nicer on the eyes, for short comments.  and death to capital
// letters.  and oooh, vim auto-extends // comments, thats handy isn't
// it! :-]

j.
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

^ permalink raw reply	[flat|nested] 52+ messages in thread

* RE: Coding Style
@ 2001-01-23 15:07 Jonathan Earle
  2001-01-24  3:23 ` john slee
  0 siblings, 1 reply; 52+ messages in thread
From: Jonathan Earle @ 2001-01-23 15:07 UTC (permalink / raw)
  To: 'Linux Kernel List'

> -----Original Message-----
> From: adrian
> 
> On Mon, 22 Jan 2001, Mark I Manning IV 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).
>  */

I like this style for multiple line comments, but prefer the '//' for single
liners.  Two less characters to type after all.  :)
 
> int function(int x)
> {
> 	/* Bleh.  Comments take up space.
> 	 */
> 	function body;
> }

int function(int x) {
 	// I like comments.  'Sides, what else would you use the space for?
 	function body;
}

Cheers!
Jon
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: Coding Style
  2001-01-20 15:32   ` Anton Altaparmakov
@ 2001-01-21  8:24     ` george anzinger
  0 siblings, 0 replies; 52+ messages in thread
From: george anzinger @ 2001-01-21  8:24 UTC (permalink / raw)
  To: Anton Altaparmakov; +Cc: Linus Torvalds, Mark I Manning IV, Kernel Mailing List

Anton Altaparmakov wrote:

> At 06:29 20/01/2001, Linus Torvalds wrote:
> 
>> On Fri, 19 Jan 2001, Mark I Manning IV wrote:
> 
> [snip]
> 
>>  > > And two spaces is not enough. If you write code that needs 
>> comments at
>>  > > the end of a line, your code is crap.
>>  >
>>  > Might i ask you to qualify that statement ?
>> 
>> Ok. I'll qualify it. Add a "unless you write in assembly language" to the
>> end. I have to admit that most assembly languages are terse and hard to
>> read enough that you often want to comment at the end. In assembly you
>> just don't tend to have enough flexibility to make the code readable, so
>> you must live with unreadable code that is commented.
> 
> 
> Would you not also add "unless you are defining structure definitions 
> and want to explain what each of the struct members means"?
> 
> [snip]
> 
>> Notice? Not AFTER the statements.
>> 
>> Why? Because you are likely to want to change the statements. You don't
>> want to keep moving the comments around to line them up. And trying to
>> have a multi-line comment with code is just HORRIBLE:
> 
> 
> And structs are not likely to change so this argument would not longer 
> apply?
> 
> Just curious.

I am curious about another style issue.  In particular _inline_ in ".h" 
files.  The "style" for this as practiced today is about to run into a 
brick wall.  Try, for example, referring to "current->need_resched" 
within the spin_lock() macro.  I don't think you can get this to work 
with the current kernel, and if you can, a) let me know how, and b) it 
is much too hard.  Imho it is time to rethink how (or where) we put 
_inline_ code.

I think the problem could be fixed by a convention in the compiler that 
says something like "_inline_" code will be compiled when a reference to 
it is encountered, but this is outside the standard (i.e. the standard 
allows it to be as it is and does not disallow my proposed convention, 
as I understand the standard).

George




-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: Coding Style
       [not found] ` <3A68E309.2540A5E1@purplecoder.com>
  2001-01-20  6:29   ` Linus Torvalds
@ 2001-01-20 15:32   ` Anton Altaparmakov
  2001-01-21  8:24     ` george anzinger
  1 sibling, 1 reply; 52+ messages in thread
From: Anton Altaparmakov @ 2001-01-20 15:32 UTC (permalink / raw)
  To: Linus Torvalds; +Cc: Mark I Manning IV, Kernel Mailing List

At 06:29 20/01/2001, Linus Torvalds wrote:
>On Fri, 19 Jan 2001, Mark I Manning IV wrote:
[snip]
> > > And two spaces is not enough. If you write code that needs comments at
> > > the end of a line, your code is crap.
> >
> > Might i ask you to qualify that statement ?
>
>Ok. I'll qualify it. Add a "unless you write in assembly language" to the
>end. I have to admit that most assembly languages are terse and hard to
>read enough that you often want to comment at the end. In assembly you
>just don't tend to have enough flexibility to make the code readable, so
>you must live with unreadable code that is commented.

Would you not also add "unless you are defining structure definitions and 
want to explain what each of the struct members means"?

[snip]
>Notice? Not AFTER the statements.
>
>Why? Because you are likely to want to change the statements. You don't
>want to keep moving the comments around to line them up. And trying to
>have a multi-line comment with code is just HORRIBLE:

And structs are not likely to change so this argument would not longer apply?

Just curious.

Regards,

         Anton


-- 
    "Programmers never die. They do a GOSUB without RETURN." - Unknown source
-- 
Anton Altaparmakov <aia21 at cam.ac.uk> (replace at with @)
Linux NTFS Maintainer
ICQ: 8561279 / WWW: http://www-stu.christs.cam.ac.uk/~aia21/

-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

^ permalink raw reply	[flat|nested] 52+ messages in thread

* Re: Coding Style
       [not found] ` <3A68E309.2540A5E1@purplecoder.com>
@ 2001-01-20  6:29   ` Linus Torvalds
  2001-01-20 15:32   ` Anton Altaparmakov
  1 sibling, 0 replies; 52+ messages in thread
From: Linus Torvalds @ 2001-01-20  6:29 UTC (permalink / raw)
  To: Mark I Manning IV; +Cc: Kernel Mailing List



On Fri, 19 Jan 2001, Mark I Manning IV wrote:
> 
> Two spaces are perfect, they delineate the blocks very nicely and dont
> eat up the comments real estate.

WHAT "comments real estate". You have tons of real estate - up and down.
Don't try to move it sideways where it won't fit anyway.

Write comments before your function. If your function is so long and
complicated that you think it needs comments after the lines, then you
should have split it up. See "function growth hormone imbalance".

> > And two spaces is not enough. If you write code that needs comments at
> > the end of a line, your code is crap.
> 
> Might i ask you to qualify that statement ?

Ok. I'll qualify it. Add a "unless you write in assembly language" to the
end. I have to admit that most assembly languages are terse and hard to
read enough that you often want to comment at the end. In assembly you
just don't tend to have enough flexibility to make the code readable, so
you must live with unreadable code that is commented.

> I disagree, comments should be associated with the code they are
> describing, putting a block of comments before a function telling people
> waht it does does nothign to tell them HOW it does it.  

Just add a "how it does it" section to your comment.

Or add your comments inside the function if you really want to localize
them, but do it something like this:

	/*
	 * my_integer_pi()
	 *
	 * This function calculates the value of PI, and returns
	 * 3. It does so by adding "1" in a loop three times.
	 */
	int my_integer_pi(void)
	{
		int i, pi;

		/*
		 * This is the main loop.
		 */
		pi = 0;
		for (i = 0; i < 3; i++)
			pi++;

		/* Ok, return it */
		return pi;
	}

Notice? Not AFTER the statements. 

Why? Because you are likely to want to change the statements. You don't
want to keep moving the comments around to line them up. And trying to
have a multi-line comment with code is just HORRIBLE:

		pi = 0;			/* Initialize our counter  */
		for (i = 0; i < 3; i++)	/* to zero before the loop */
			pi++;		/* Increment it.	   */

because the above turns into absolute mush if you change your code a bit
(maybe you decide to move the initialization up a bit, because you make
your function start off with a better approximation, and you want to use
another algorithm to calculate PI to more than zero decimal points. Now
you need to move the two-line comment around, and break it up etc etc.

In contrast, when you have comments on lines of their own, you just move
the whole comment block when you re-organize the code.

		Linus

-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

^ permalink raw reply	[flat|nested] 52+ messages in thread

end of thread, other threads:[~2007-06-19 14:05 UTC | newest]

Thread overview: 52+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2001-01-19 17:59 Coding Style Mark I Manning IV
2001-01-20  0:09 ` David Ford
2001-01-20  1:26   ` John Cavan
2001-01-20  0:46 ` Albert D. Cahalan
2001-01-20  5:34   ` Linus Torvalds
2001-01-21  2:00 ` Matthias Andree
2001-01-22  8:24   ` Ralf Baechle
2001-01-22 22:28     ` Mark I Manning IV
2001-01-23  3:56       ` adrian
2001-01-23 20:05 ` Boris Dragovic
     [not found] <Pine.LNX.4.10.10101192217390.9361-100000@penguin.transmeta .com>
     [not found] ` <3A68E309.2540A5E1@purplecoder.com>
2001-01-20  6:29   ` Linus Torvalds
2001-01-20 15:32   ` Anton Altaparmakov
2001-01-21  8:24     ` george anzinger
2001-01-23 15:07 Jonathan Earle
2001-01-24  3:23 ` john slee
2007-06-14 18:48 coding style Cyrill Gorcunov
2007-06-15  4:51 ` Willy Tarreau
2007-06-15  5:09   ` Kok, Auke
2007-06-15  6:38     ` dave young
2007-06-15  6:47       ` debian developer
2007-06-15  6:54         ` dave young
2007-06-15  9:16       ` Jan Engelhardt
2007-06-15 17:32         ` Cyrill Gorcunov
2007-06-15 17:54           ` Chris Friesen
2007-06-15 18:03             ` Randy Dunlap
2007-06-15 19:10               ` Jan Engelhardt
2007-06-15 19:18                 ` Cyrill Gorcunov
2007-06-15 19:21                   ` Kok, Auke
2007-06-15 19:29                     ` Cyrill Gorcunov
2007-06-15 19:31                     ` Jan Engelhardt
2007-06-15 19:41                       ` Cyrill Gorcunov
2007-06-15 20:21                         ` Linus Torvalds
2007-06-15 20:35                           ` Jan Engelhardt
2007-06-16 12:30                             ` Stefan Richter
2007-06-15 20:21                         ` Jan Engelhardt
2007-06-15 20:39                           ` Linus Torvalds
2007-06-16  6:38                             ` Jan Engelhardt
2007-06-16 12:40                               ` Stefan Richter
2007-06-16 15:49                               ` Linus Torvalds
2007-06-19 14:05                                 ` Mark Lord
2007-06-15 19:45                       ` Kok, Auke
2007-06-15 19:49                         ` Cyrill Gorcunov
2007-06-15 20:28                         ` Jan Engelhardt
2007-06-15 22:10                   ` Randy Dunlap
2007-06-15 18:05             ` Kok, Auke
2007-06-15 18:22               ` Cyrill Gorcunov
2007-06-16 13:07                 ` Stefan Richter
2007-06-16 14:31                   ` gorcunov
2007-06-16 17:43                     ` Stefan Richter
2007-06-16 18:22                       ` Cyrill Gorcunov
2007-06-16 14:22         ` Clifford Wolf
2007-06-15  8:56     ` Krzysztof Halasa

This is a public inbox, see mirroring instructions
on how to clone and mirror all data and code used for this inbox