coding style

coding style

[Cyrill Gorcunov]

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

Re: coding style

[Willy Tarreau]

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

Re: coding style

[Kok, Auke]

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

Re: coding style

[dave young]

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

Re: coding style

[debian developer]

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.

Re: coding style

[dave young]

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

Mailing style (was Re: coding style)

[Bernd Petrovitsch]

On Fri, 2007-06-15 at 12:17 +0530, debian developer wrote:
[...]
> And *Please* do not top-post!

Says the one without real name who is full quoting including even the
mailing list footers.

SCNR,
	Bernd
-- 
Firmix Software GmbH                   http://www.firmix.at/
mobil: +43 664 4416156                 fax: +43 1 7890849-55
          Embedded Linux Development and Services

Re: Mailing style (was Re: coding style)

[debian developer]

On 6/15/07, Bernd Petrovitsch <bernd@firmix.at> wrote:

> Says the one without real name who is full quoting including even the
> mailing list footers.

hmm. including footers was a mistake. sigh!
but i really dont understand why the real name is needed unless im
submitting some patches!

"What's in a name?"
- somebody( googled, but could'nt find it ;) )

Re: coding style

[Jan Engelhardt]

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

Re: coding style

[Cyrill Gorcunov]

[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

Re: coding style

[Chris Friesen]

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

Re: coding style

[Randy Dunlap]

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

Re: coding style

[Jan Engelhardt]

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

Re: coding style

[Cyrill Gorcunov]

[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

Re: coding style

[Kok, Auke]

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

Re: coding style

[Cyrill Gorcunov]

[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

Re: coding style

[Jan Engelhardt]

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

Re: coding style

[Cyrill Gorcunov]

[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

Re: coding style

[Linus Torvalds]

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

Re: coding style

[Jan Engelhardt]

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

Re: coding style

[Stefan Richter]

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/

Re: coding style

[Jan Engelhardt]

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

Re: coding style

[Linus Torvalds]

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

Re: coding style

[Jan Engelhardt]

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

Re: coding style

[Stefan Richter]

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/

Re: coding style

[Linus Torvalds]

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

Re: coding style

[Mark Lord]

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.

Re: coding style

[Kok, Auke]

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

Re: coding style

[Cyrill Gorcunov]

[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

Re: coding style

[Jan Engelhardt]

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

Re: coding style

[Randy Dunlap]

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

please keep the CodingStyle text in check (was Re: coding style)

[Stefan Richter]

Randy Dunlap wrote:
> On Fri, 15 Jun 2007 23:18:04 +0400 Cyrill Gorcunov wrote:
>> 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.

People seem to forget:

   - CodingStyle is a lot about agreement and existing practice.

   - A longer, bulkier, convoluted, bureaucratic CodingStyle will not
     enhance quality of contributions.
-- 
Stefan Richter
-=====-=-=== -==- =----
http://arcgraph.de/sr/

Re: coding style

[Kok, Auke]

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

Re: coding style

[Cyrill Gorcunov]

[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

Re: coding style

[Stefan Richter]

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/

Re: coding style

[gorcunov]

[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

Re: coding style

[Stefan Richter]

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/

Re: coding style

[Cyrill Gorcunov]

[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

Re: coding style

[Clifford Wolf]

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.

Re: coding style

[Krzysztof Halasa]

"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