Relaxing the 'tab = 8 character', which leads to 'don't tab the alignment'.
By only using tabs for indentation, we solidify it as a 'logical indentation'.
Signed-off-by: Richard Knutsson <[email protected]>
---
To'ed the people who showed interest in the (apparently not so new)
question/suggestion of not using tabs when aligning.
If this looks ok, then checkpatch.pl is next...
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
index 6caa146..1b3f448 100644
--- a/Documentation/CodingStyle
+++ b/Documentation/CodingStyle
@@ -15,10 +15,8 @@ Anyway, here goes:
Chapter 1: Indentation
-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.
+This project is recommended to be viewed with a tab-width of 8 characters
+(and other code).
Rationale: The whole idea behind indentation is to clearly define where
a block of control starts and ends. Especially when you've been looking
@@ -86,13 +84,15 @@ substantially to the right. The same applies to function
headers with a long
argument list. Long strings are as well broken into shorter strings. The
only exception to this is where exceeding 80 columns significantly increases
readability and does not hide information.
+As this falls under alignments, only use tabs to indent it to the parents
+level and then space in the rest.
void fun(int a, int b, int c)
{
if (condition)
printk(KERN_WARNING "Warning this is a long printk with "
- "3 parameters a: %u b: %u "
- "c: %u \n", a, b, c);
+ "3 parameters a: %u b: %u "
+ "c: %u \n", a, b, c);
else
next_statement;
}
On Tue, 26 Feb 2008 22:47:10 +0100 [email protected] wrote:
> Relaxing the 'tab = 8 character', which leads to 'don't tab the alignment'.
> By only using tabs for indentation, we solidify it as a 'logical indentation'.
>
> Signed-off-by: Richard Knutsson <[email protected]>
> ---
> To'ed the people who showed interest in the (apparently not so new)
> question/suggestion of not using tabs when aligning.
> If this looks ok, then checkpatch.pl is next...
>
>
> diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
> index 6caa146..1b3f448 100644
> --- a/Documentation/CodingStyle
> +++ b/Documentation/CodingStyle
> @@ -15,10 +15,8 @@ Anyway, here goes:
>
> Chapter 1: Indentation
>
> -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.
> +This project is recommended to be viewed with a tab-width of 8 characters
> +(and other code).
FWIW I prefer the {deleted} language. // PI = 3;
> Rationale: The whole idea behind indentation is to clearly define where
> a block of control starts and ends. Especially when you've been looking
---
~Randy
Randy Dunlap wrote:
> On Tue, 26 Feb 2008 22:47:10 +0100 [email protected] wrote:
>
>
>> Relaxing the 'tab = 8 character', which leads to 'don't tab the alignment'.
>> By only using tabs for indentation, we solidify it as a 'logical indentation'.
>>
>> Signed-off-by: Richard Knutsson <[email protected]>
>> ---
>> To'ed the people who showed interest in the (apparently not so new)
>> question/suggestion of not using tabs when aligning.
>> If this looks ok, then checkpatch.pl is next...
>>
>>
>> diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
>> index 6caa146..1b3f448 100644
>> --- a/Documentation/CodingStyle
>> +++ b/Documentation/CodingStyle
>> @@ -15,10 +15,8 @@ Anyway, here goes:
>>
>> Chapter 1: Indentation
>>
>> -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.
>> +This project is recommended to be viewed with a tab-width of 8 characters
>> +(and other code).
>>
>
> FWIW I prefer the {deleted} language. // PI = 3;
>
Well, actually I like it too. But I think it should be up to the
programmer which setting to use + it seems some people have really taken
this to heart, going from 'tab => 8 characters wide' to '8 spaces =>
tab', obscuring tab's position as a 'logical indention'.
Richard Knutsson
On Feb 26 2008 13:54, Randy Dunlap wrote:
>> Chapter 1: Indentation
>>
>> -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.
>> +This project is recommended to be viewed with a tab-width of 8 characters
>> +(and other code).
>
>FWIW I prefer the {deleted} language. // PI = 3;
The whole paragraph is misworded anyway (before and after), because
it never says one has to use tabs. Just that tabs are 8. Oh wow.
Here's a rewording of everything I am unhappy with, and it goes
a bit further than tabs and spaces.
It may all sound like we are trying to be nitpicky about minuscule
things, but obviously, if there is a way to go against common practice
but still comply to CS, someone will do it in some patch.
Signed-off-by: Jan Engelhardt <[email protected]>
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
index 6caa146..d80fd0f 100644
--- a/Documentation/CodingStyle
+++ b/Documentation/CodingStyle
@@ -15,23 +15,25 @@ Anyway, here goes:
Chapter 1: Indentation
-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.
+The whole idea behind indentation is to clearly define where a block of
+control starts and ends.
-Rationale: The whole idea behind indentation is to clearly define where
-a block of control starts and ends. Especially when you've been looking
-at your screen for 20 straight hours, you'll find it a lot easier to see
-how the indentation works if you have large indentations.
+There are heretic movements that try to use spaces for indentation. But
+spaces force a specific indentation width on the user. Tabs on the other
+hand provide logical indentation, which means you can set the tab width
+in your editor preferences to any value you like. Especially when you
+have been looking at your screen for 20 straight hours, you will find it
+a lot easier if you can dynamically switch to a higher indent.
-Now, some people will claim that having 8-character indentations makes
+By default, tabs have a width of 8, and most developers use that.
+
+Now, some people will claim that having an 8-wide 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 short, 8-char indents make things easier to read, and have the added
+In short, 8-wide indents make things easier to read, and have the added
benefit of warning you when you're nesting your functions too deep.
Heed that warning.
@@ -77,26 +79,51 @@ Get a decent editor and don't leave whitespace at the end of lines.
Coding style is all about readability and maintainability using commonly
available tools.
-The limit on the length of lines is 80 columns and this is a strongly
-preferred limit.
+The limit on the length of lines is 80 columns, that is when tabs are
+displayed with a size of 8. 80 columns is a strongly preferred limit.
+
+Statements longer than 80 columns should be broken into sensible chunks.
+
+Continuation lines are always shorter than the initial one and are
+(1) indented as much as the initial line, plus (2) alignment spaces.
+Spaces are used so as to not cause odd aligning for users wishing to
+display tabs at sizes other than 8. In the example below, the
+continuation line of the printk call therefore has two tabs of logical
+indent, followed by a number of spaces to align it up.
-Statements longer than 80 columns will be broken into sensible chunks.
-Descendants are always substantially shorter than the parent and are placed
-substantially to the right. The same applies to function headers with a long
-argument list. Long strings are as well broken into shorter strings. The
-only exception to this is where exceeding 80 columns significantly increases
-readability and does not hide information.
+The same applies to function headers with a long argument list. Long
+strings are broken as well into shorter strings. The only exception to
+this is where exceeding 80 columns significantly increases readability
+and does not hide information.
-void fun(int a, int b, int c)
+void fun(int a, int b, int c, struct very_big_structure *ptr,
+ struct lots_of_parameters *ptr2)
{
if (condition)
printk(KERN_WARNING "Warning this is a long printk with "
- "3 parameters a: %u b: %u "
- "c: %u \n", a, b, c);
+ "3 parameters a: %u b: %u c: %u\n"
+ "And our poitners are %p and %p\n",
+ a, b, c);
else
next_statement;
}
+When the function return type, tags and name already takes up a
+significant amount of valuable 80-column space, it is recommended to
+split the long line before the name to reduce the amount of indent
+needed for parameters.
+
+static int __init longmodule_initialize_driver(struct pci_driver *foo,
+ void *some_parameter,
+ void *another_parameter)
+
+into
+
+static int __init
+longmodule_initialize_driver(struct pci_driver *foo, void *some_parameter,
+ void *another_parameter)
+
+
Chapter 3: Placing Braces and Spaces
The other issue that always comes up in C styling is the placement of
@@ -134,7 +161,7 @@ opening brace at the beginning of the next line, thus:
Heretic people all over the world have claimed that this inconsistency
is ... well ... inconsistent, but all right-thinking people know that
(a) K&R are _right_ and (b) K&R are right. Besides, functions are
-special anyway (you can't nest them in C).
+special anyway (you can't nest them in standard C).
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,
@@ -178,7 +205,7 @@ if (condition) {
otherwise();
}
- 3.1: Spaces
+ Subchapter 3.1: Spaces
Linux kernel style for use of spaces depends (mostly) on
function-versus-keyword usage. Use a space after (most) keywords. The
@@ -342,6 +369,10 @@ EVER use a typedef unless you can clearly match one of those rules.
In general, a pointer, or a struct that has elements that can reasonably
be directly accessed should _never_ be a typedef.
+Also, using typedefs always requires to #include the header they are
+defined in. If a predeclaration of a struct or union suffices to compile
+the unit without including the header, you even get a speedup.
+
Chapter 6: Functions
On Tue, 26 Feb 2008, Jan Engelhardt wrote:
> +Continuation lines are always shorter than the initial one and are
> +(1) indented as much as the initial line, plus (2) alignment spaces.
> +Spaces are used so as to not cause odd aligning for users wishing to
> +display tabs at sizes other than 8. In the example below, the
> +continuation line of the printk call therefore has two tabs of logical
> +indent, followed by a number of spaces to align it up.
Now, I think, I am not the only one using emacs. Until now the "linux"
C-style fitted perfectly with the CodingStyle, now it no longer will.
Namely, emacs puts as many tabs to indent the continuation line as fit
(i.e., at tab width = 8 spaces it's just (extra indent / 8) tabs plus
(extra indent % 8) spaces. Is there a way to make emacs behave compatibly
to this proposal? If not, I would not like to have to re-indent every such
line manually or have my patches rejected because of this.
Thanks
Guennadi
---
Guennadi Liakhovetski
Guennadi Liakhovetski <[email protected]> writes:
> Now, I think, I am not the only one using emacs. Until now the "linux"
> C-style fitted perfectly with the CodingStyle, now it no longer will.
> Namely, emacs puts as many tabs to indent the continuation line as fit
> (i.e., at tab width = 8 spaces it's just (extra indent / 8) tabs plus
> (extra indent % 8) spaces. Is there a way to make emacs behave compatibly
> to this proposal? If not, I would not like to have to re-indent every such
> line manually or have my patches rejected because of this.
Oh, I'm sure nobody will reject patches because of this now. It would
mean no patches are accepted.
Hopefully an elisp expert will implement it. Vim people probably need
something like that as well, and the list of editors is a bit longer...
--
Krzysztof Halasa
On Feb 27 2008 00:51, Krzysztof Halasa wrote:
>Guennadi Liakhovetski <[email protected]> writes:
>
>> Now, I think, I am not the only one using emacs. Until now the "linux"
>> C-style fitted perfectly with the CodingStyle, now it no longer will.
>> Namely, emacs puts as many tabs to indent the continuation line as fit
>> (i.e., at tab width = 8 spaces it's just (extra indent / 8) tabs plus
>> (extra indent % 8) spaces. Is there a way to make emacs behave compatibly
>> to this proposal? If not, I would not like to have to re-indent every such
>> line manually or have my patches rejected because of this.
>
>Oh, I'm sure nobody will reject patches because of this now. It would
>mean no patches are accepted.
Correct. Just did not want to even encourage any newcomers to use
tabs when spacing is needed. Though, some editors unfortunately do
just that - replacing 8 spaces by tabs on a new line when autoindent
is on, like mcedit :-(
On Feb. 26, 2008, 14:16 -0800, Richard Knutsson <[email protected]> wrote:
> Randy Dunlap wrote:
>> On Tue, 26 Feb 2008 22:47:10 +0100 [email protected] wrote:
>>
>>
>>> Relaxing the 'tab = 8 character', which leads to 'don't tab the alignment'.
>>> By only using tabs for indentation, we solidify it as a 'logical indentation'.
>>>
>>> Signed-off-by: Richard Knutsson <[email protected]>
>>> ---
>>> To'ed the people who showed interest in the (apparently not so new)
>>> question/suggestion of not using tabs when aligning.
>>> If this looks ok, then checkpatch.pl is next...
>>>
>>>
>>> diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
>>> index 6caa146..1b3f448 100644
>>> --- a/Documentation/CodingStyle
>>> +++ b/Documentation/CodingStyle
>>> @@ -15,10 +15,8 @@ Anyway, here goes:
>>>
>>> Chapter 1: Indentation
>>>
>>> -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.
>>> +This project is recommended to be viewed with a tab-width of 8 characters
>>> +(and other code).
>>>
>> FWIW I prefer the {deleted} language. // PI = 3;
>>
> Well, actually I like it too. But I think it should be up to the
> programmer which setting to use + it seems some people have really taken
> this to heart, going from 'tab => 8 characters wide' to '8 spaces =>
> tab', obscuring tab's position as a 'logical indention'.
>
> Richard Knutsson
>
How about this:
-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.
+Tabs are used for logical indentation, e.g., code is indented with
+a number of tabs equal to its nesting level. From there on,
+use space characters for decorative indentation. This method
+is agnostic to the editor's tab-expansion settings.
+That said, expanding tabs to a small number of spaces (4, or even 2!) encourages
+excessive nesting and resulting over-complexity; that is akin to trying to define
+the value of PI to be 3. Therefore, tabs are always assumed to be 8 characters-wide.
On Wed, 27 Feb 2008, Jan Engelhardt wrote:
>
> On Feb 27 2008 00:51, Krzysztof Halasa wrote:
> >Guennadi Liakhovetski <[email protected]> writes:
> >
> >> Now, I think, I am not the only one using emacs. Until now the "linux"
> >> C-style fitted perfectly with the CodingStyle, now it no longer will.
> >> Namely, emacs puts as many tabs to indent the continuation line as fit
> >> (i.e., at tab width = 8 spaces it's just (extra indent / 8) tabs plus
> >> (extra indent % 8) spaces. Is there a way to make emacs behave compatibly
> >> to this proposal? If not, I would not like to have to re-indent every such
> >> line manually or have my patches rejected because of this.
> >
> >Oh, I'm sure nobody will reject patches because of this now. It would
> >mean no patches are accepted.
>
> Correct. Just did not want to even encourage any newcomers to use
> tabs when spacing is needed. Though, some editors unfortunately do
> just that - replacing 8 spaces by tabs on a new line when autoindent
> is on, like mcedit :-(
Then why do we define rules that we know that nobody will (be reasonably
able to) adhere to?
I can see the reasoning behind using spaces instead of tabs in
continuation lines and in in-line indentation like
int x = 1;
void *c = NULL;
or
#define X 1
#define XY 2
although I personally perfer TABs there too. But as long as we do not want
to actually impose that, I don't think we should define that.
Whereas an explicit rule requesting to use TABs and not spaces for
different indentation levels seems good.
Thanks
Guennadi
---
Guennadi Liakhovetski
Jan Engelhardt, Benny Halevy, and Richard Knutsson wrote:
> -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.
Don't do this.
--
Stefan Richter
-=====-==--- --=- ==-==
http://arcgraph.de/sr/
Jan Engelhardt wrote:
> Just did not want to even encourage any newcomers to [...]
Instead, start to encourage newcomers to help us fix bugs.
Thanks.
--
Stefan Richter
-=====-==--- --=- ==-==
http://arcgraph.de/sr/
On 2/26/08, Krzysztof Halasa <[email protected]> wrote:
> Hopefully an elisp expert will implement it. Vim people probably need
> something like that as well, and the list of editors is a bit longer...
The proposed two space change is ugly. Can someone NAK it?
-sb (The elisp guy who added the linux c-style)
On Tue, 26 Feb 2008 16:57:47 -0800 SL Baur wrote:
> On 2/26/08, Krzysztof Halasa <[email protected]> wrote:
>
> > Hopefully an elisp expert will implement it. Vim people probably need
> > something like that as well, and the list of editors is a bit longer...
>
> The proposed two space change is ugly. Can someone NAK it?
>
> -sb (The elisp guy who added the linux c-style)
I would gladly NAK it, but most recent email from Linus about
coding style is that we are getting too detailed about it,
so unless there is some overwhelming need to change anything in
CodingStyle, I'm for no changes (or maybe even some removals).
---
~Randy
On Mit, 2008-02-27 at 00:40 +0100, Guennadi Liakhovetski wrote:
> On Tue, 26 Feb 2008, Jan Engelhardt wrote:
>
> > +Continuation lines are always shorter than the initial one and are
> > +(1) indented as much as the initial line, plus (2) alignment spaces.
> > +Spaces are used so as to not cause odd aligning for users wishing to
> > +display tabs at sizes other than 8. In the example below, the
> > +continuation line of the printk call therefore has two tabs of logical
> > +indent, followed by a number of spaces to align it up.
>
> Now, I think, I am not the only one using emacs. Until now the "linux"
> C-style fitted perfectly with the CodingStyle, now it no longer will.
> Namely, emacs puts as many tabs to indent the continuation line as fit
> (i.e., at tab width = 8 spaces it's just (extra indent / 8) tabs plus
> (extra indent % 8) spaces. Is there a way to make emacs behave compatibly
> to this proposal? If not, I would not like to have to re-indent every such
Unless I'm misunderstanding something completely: Add "indent-tabs-mode:
nil" in a "Local Variables:" section.
But since Linux-style has that since ages (if not ever), that should be
set for am emacs'ens linux-mode anyway.
Bernd
--
Firmix Software GmbH http://www.firmix.at/
mobil: +43 664 4416156 fax: +43 1 7890849-55
Embedded Linux Development and Services
On Wed, 27 Feb 2008, Bernd Petrovitsch wrote:
> On Mit, 2008-02-27 at 00:40 +0100, Guennadi Liakhovetski wrote:
> > On Tue, 26 Feb 2008, Jan Engelhardt wrote:
> >
> > > +Continuation lines are always shorter than the initial one and are
> > > +(1) indented as much as the initial line, plus (2) alignment spaces.
> > > +Spaces are used so as to not cause odd aligning for users wishing to
> > > +display tabs at sizes other than 8. In the example below, the
> > > +continuation line of the printk call therefore has two tabs of logical
> > > +indent, followed by a number of spaces to align it up.
> >
> > Now, I think, I am not the only one using emacs. Until now the "linux"
> > C-style fitted perfectly with the CodingStyle, now it no longer will.
> > Namely, emacs puts as many tabs to indent the continuation line as fit
> > (i.e., at tab width = 8 spaces it's just (extra indent / 8) tabs plus
> > (extra indent % 8) spaces. Is there a way to make emacs behave compatibly
> > to this proposal? If not, I would not like to have to re-indent every such
>
> Unless I'm misunderstanding something completely: Add "indent-tabs-mode:
> nil" in a "Local Variables:" section.
> But since Linux-style has that since ages (if not ever), that should be
> set for am emacs'ens linux-mode anyway.
I think you do misunderstand something. The "linux" emacs mode as I know
it does for the following example
1: function(arg1,
2: arg2);
in line 2 two TABs and one space. Whereas the proposal in discussion wants
to have there one TAB and nine spaces.
Thanks
Guennadi
---
Guennadi Liakhovetski
On Mit, 2008-02-27 at 11:02 +0100, Guennadi Liakhovetski wrote:
> On Wed, 27 Feb 2008, Bernd Petrovitsch wrote:
>
> > On Mit, 2008-02-27 at 00:40 +0100, Guennadi Liakhovetski wrote:
> > > On Tue, 26 Feb 2008, Jan Engelhardt wrote:
> > >
> > > > +Continuation lines are always shorter than the initial one and are
> > > > +(1) indented as much as the initial line, plus (2) alignment spaces.
> > > > +Spaces are used so as to not cause odd aligning for users wishing to
> > > > +display tabs at sizes other than 8. In the example below, the
> > > > +continuation line of the printk call therefore has two tabs of logical
> > > > +indent, followed by a number of spaces to align it up.
> > >
> > > Now, I think, I am not the only one using emacs. Until now the "linux"
> > > C-style fitted perfectly with the CodingStyle, now it no longer will.
> > > Namely, emacs puts as many tabs to indent the continuation line as fit
> > > (i.e., at tab width = 8 spaces it's just (extra indent / 8) tabs plus
> > > (extra indent % 8) spaces. Is there a way to make emacs behave compatibly
> > > to this proposal? If not, I would not like to have to re-indent every such
> >
> > Unless I'm misunderstanding something completely: Add "indent-tabs-mode:
> > nil" in a "Local Variables:" section.
> > But since Linux-style has that since ages (if not ever), that should be
> > set for am emacs'ens linux-mode anyway.
>
> I think you do misunderstand something. The "linux" emacs mode as I know
Yes, I`m silly - -ENOCOFFEE;-) CodingStyle/"linux-mode" *does* use TABs
since ever.
> it does for the following example
>
> 1: function(arg1,
> 2: arg2);
>
> in line 2 two TABs and one space. Whereas the proposal in discussion wants
> to have there one TAB and nine spaces.
I stand corrected, you are right.
Bernd
--
Firmix Software GmbH http://www.firmix.at/
mobil: +43 664 4416156 fax: +43 1 7890849-55
Embedded Linux Development and Services
Benny Halevy wrote:
>
> How about this:
>
> -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.
> +Tabs are used for logical indentation, e.g., code is indented with
> +a number of tabs equal to its nesting level. From there on,
> +use space characters for decorative indentation. This method
> +is agnostic to the editor's tab-expansion settings.
> +That said, expanding tabs to a small number of spaces (4, or even 2!) encourages
> +excessive nesting and resulting over-complexity; that is akin to trying to define
> +the value of PI to be 3. Therefore, tabs are always assumed to be 8 characters-wide.
>
>
Not sure about the PI-reference in that context, but the rest IMO looks
good.
On 2/26/08, Randy Dunlap <[email protected]> wrote:
> On Tue, 26 Feb 2008 16:57:47 -0800 SL Baur wrote:
> > The proposed two space change is ugly. Can someone NAK it?
> I would gladly NAK it, but most recent email from Linus about
> coding style is that we are getting too detailed about it,
I agree and a NAK is a vote for not changing anything. Thanks.
-sb
> > FWIW I prefer the {deleted} language. // PI = 3;
> >
> Well, actually I like it too. But I think it should be up to the
> programmer which setting to use + it seems some people have really taken
> this to heart, going from 'tab => 8 characters wide' to '8 spaces =>
> tab', obscuring tab's position as a 'logical indention'.
Well, no one's saying that you can't configure your editor any way you
want. The tabs=8 is a good cue for the 80-column rule, though.
IMO, CodingStyle used to be a good, funny read and now it's just simply
full of boring pedantic laws.
-Bob
Jan Engelhardt wrote:
> On Feb 26 2008 13:54, Randy Dunlap wrote:
>
>>> Chapter 1: Indentation
>>>
>>> -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.
>>> +This project is recommended to be viewed with a tab-width of 8 characters
>>> +(and other code).
>>>
>> FWIW I prefer the {deleted} language. // PI = 3;
>>
>
> The whole paragraph is misworded anyway (before and after), because
> it never says one has to use tabs. Just that tabs are 8. Oh wow.
>
> Here's a rewording of everything I am unhappy with, and it goes
> a bit further than tabs and spaces.
>
> It may all sound like we are trying to be nitpicky about minuscule
> things, but obviously, if there is a way to go against common practice
> but still comply to CS, someone will do it in some patch.
>
>
> Signed-off-by: Jan Engelhardt <[email protected]>
>
>
> diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
> index 6caa146..d80fd0f 100644
> --- a/Documentation/CodingStyle
> +++ b/Documentation/CodingStyle
> @@ -15,23 +15,25 @@ Anyway, here goes:
>
> Chapter 1: Indentation
>
> -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.
> +The whole idea behind indentation is to clearly define where a block of
> +control starts and ends.
>
> -Rationale: The whole idea behind indentation is to clearly define where
> -a block of control starts and ends. Especially when you've been looking
> -at your screen for 20 straight hours, you'll find it a lot easier to see
> -how the indentation works if you have large indentations.
> +There are heretic movements that try to use spaces for indentation. But
> +spaces force a specific indentation width on the user. Tabs on the other
> +hand provide logical indentation, which means you can set the tab width
> +in your editor preferences to any value you like. Especially when you
> +have been looking at your screen for 20 straight hours, you will find it
> +a lot easier if you can dynamically switch to a higher indent.
>
> -Now, some people will claim that having 8-character indentations makes
> +By default, tabs have a width of 8, and most developers use that.
> +
> +Now, some people will claim that having an 8-wide 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 short, 8-char indents make things easier to read, and have the added
> +In short, 8-wide indents make things easier to read, and have the added
> benefit of warning you when you're nesting your functions too deep.
> Heed that warning.
>
> @@ -77,26 +79,51 @@ Get a decent editor and don't leave whitespace at the end of lines.
> Coding style is all about readability and maintainability using commonly
> available tools.
>
> -The limit on the length of lines is 80 columns and this is a strongly
> -preferred limit.
> +The limit on the length of lines is 80 columns, that is when tabs are
> +displayed with a size of 8. 80 columns is a strongly preferred limit.
> +
> +Statements longer than 80 columns should be broken into sensible chunks.
> +
> +Continuation lines are always shorter than the initial one and are
> +(1) indented as much as the initial line, plus (2) alignment spaces.
> +Spaces are used so as to not cause odd aligning for users wishing to
> +display tabs at sizes other than 8. In the example below, the
> +continuation line of the printk call therefore has two tabs of logical
> +indent, followed by a number of spaces to align it up.
>
> -Statements longer than 80 columns will be broken into sensible chunks.
> -Descendants are always substantially shorter than the parent and are placed
> -substantially to the right. The same applies to function headers with a long
> -argument list. Long strings are as well broken into shorter strings. The
> -only exception to this is where exceeding 80 columns significantly increases
> -readability and does not hide information.
> +The same applies to function headers with a long argument list. Long
> +strings are broken as well into shorter strings. The only exception to
> +this is where exceeding 80 columns significantly increases readability
> +and does not hide information.
>
Really nitpick, but (since it is already in the patch) wouldn't it be
"hide relevant information."?
>
> -void fun(int a, int b, int c)
> +void fun(int a, int b, int c, struct very_big_structure *ptr,
> + struct lots_of_parameters *ptr2)
> {
> if (condition)
> printk(KERN_WARNING "Warning this is a long printk with "
> - "3 parameters a: %u b: %u "
> - "c: %u \n", a, b, c);
> + "3 parameters a: %u b: %u c: %u\n"
> + "And our poitners are %p and %p\n",
> + a, b, c);
> else
> next_statement;
> }
>
> +When the function return type, tags and name already takes up a
> +significant amount of valuable 80-column space, it is recommended to
> +split the long line before the name to reduce the amount of indent
> +needed for parameters.
> +
> +static int __init longmodule_initialize_driver(struct pci_driver *foo,
> + void *some_parameter,
> + void *another_parameter)
> +
> +into
> +
> +static int __init
> +longmodule_initialize_driver(struct pci_driver *foo, void *some_parameter,
> + void *another_parameter)
> +
> +
> Chapter 3: Placing Braces and Spaces
>
> The other issue that always comes up in C styling is the placement of
> @@ -134,7 +161,7 @@ opening brace at the beginning of the next line, thus:
> Heretic people all over the world have claimed that this inconsistency
> is ... well ... inconsistent, but all right-thinking people know that
> (a) K&R are _right_ and (b) K&R are right. Besides, functions are
> -special anyway (you can't nest them in C).
> +special anyway (you can't nest them in standard C).
>
> 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,
> @@ -178,7 +205,7 @@ if (condition) {
> otherwise();
> }
>
> - 3.1: Spaces
> + Subchapter 3.1: Spaces
>
> Linux kernel style for use of spaces depends (mostly) on
> function-versus-keyword usage. Use a space after (most) keywords. The
> @@ -342,6 +369,10 @@ EVER use a typedef unless you can clearly match one of those rules.
> In general, a pointer, or a struct that has elements that can reasonably
> be directly accessed should _never_ be a typedef.
>
> +Also, using typedefs always requires to #include the header they are
> +defined in. If a predeclaration of a struct or union suffices to compile
> +the unit without including the header, you even get a speedup.
> +
>
> Chapter 6: Functions
>
>
Thumbs up
thanks
Richard Knutsson
On 2/27/08, Bernd Petrovitsch <[email protected]> wrote:
> Unless I'm misunderstanding something completely: Add "indent-tabs-mode:
> nil" in a "Local Variables:" section.
Yes, please don't ever do that. At the very best it's an eyesore.
At the worst it's a typical Richard Stallman misfeature. And pity the
poor programmer who happens to submit a patch containing such
magic when AKPM rains thunderbolts down from heaven to correct
the error. (Andrew sustains an incoming patch load 2 orders of
magnitude higher than I ever had to and it drove me crazy, by all
means cater to his wishes).
-sb
Bob Copeland wrote:
>> > FWIW I prefer the {deleted} language. // PI = 3;
>> >
>> Well, actually I like it too. But I think it should be up to the
>> programmer which setting to use + it seems some people have really taken
>> this to heart, going from 'tab => 8 characters wide' to '8 spaces =>
>> tab', obscuring tab's position as a 'logical indention'.
>>
>
> Well, no one's saying that you can't configure your editor any way you
> want. The tabs=8 is a good cue for the 80-column rule, though.
>
The problem isn't "should tab be <any number> wide", it is those who
want to force replacement of alignment-spaces with tabs (aka
checkpatch.pl). Also, the 80-rule is not really effective if not using
8-wide tabs ;)
> IMO, CodingStyle used to be a good, funny read and now it's just simply
> full of boring pedantic laws.
>
Unfortunately...
Randy Dunlap wrote:
> On Tue, 26 Feb 2008 16:57:47 -0800 SL Baur wrote:
>
>
>> On 2/26/08, Krzysztof Halasa <[email protected]> wrote:
>>
>>
>>> Hopefully an elisp expert will implement it. Vim people probably need
>>> something like that as well, and the list of editors is a bit longer...
>>>
>> The proposed two space change is ugly. Can someone NAK it?
>>
>> -sb (The elisp guy who added the linux c-style)
>>
>
> I would gladly NAK it, but most recent email from Linus about
> coding style is that we are getting too detailed about it,
> so unless there is some overwhelming need to change anything in
> CodingStyle, I'm for no changes (or maybe even some removals).
>
>
Not sure if it can be counted as an overwhelming need, just actually
defining the variable-wide character to be use "properly". Saw the way
through CodeStyle as the correct way to get the "replace 8-space
alignment to tab" nulled (then fix/change checkpatch.pl).
Actually, I see this as an quite simple question: is tab _the
indention-marker_? If not, then why the refusal of spaces indents (or mix)?
Richard Knutsson <[email protected]> writes:
> Actually, I see this as an quite simple question: is tab _the
> indention-marker_?
I hope so.
--
Krzysztof Halasa
On 2/27/08, Richard Knutsson <[email protected]> wrote:
> Actually, I see this as an quite simple question: is tab _the
> indention-marker_? If not, then why the refusal of spaces indents (or mix)?
Because mixing spaces and tabs is often ugly. 8 spaces and a
single tab often do not have the same width when you're viewing
the text in a variable width font.
I've read all my mail in a variable width font for over a decade, at
first to watch for regressions in the XEmacs display engine, but I
continued because I liked it. I presume I'm not the only one doing
so.
-sb
On Feb 27 2008 16:11, SL Baur wrote:
>On 2/27/08, Richard Knutsson <[email protected]> wrote:
>
>> Actually, I see this as an quite simple question: is tab _the
>> indention-marker_? If not, then why the refusal of spaces indents (or mix)?
>
>Because mixing spaces and tabs is often ugly. 8 spaces and a
>single tab often do not have the same width when you're viewing
>the text in a variable width font.
By the way, neither tab nor bunch-a'-spaces makes alignment look good.
Try:
/* fails when !monospace || tab != 8 */
fprintf(fp, KERN_WARNING
"Opening quotes should be right after (");
/* fails if !monospace */
fprintf(fp, KERN_WARNING
"Opening quotes should be right after (");
hm... :-/
SL Baur wrote:
> On 2/27/08, Richard Knutsson <[email protected]> wrote:
>
>
>> Actually, I see this as an quite simple question: is tab _the
>> indention-marker_? If not, then why the refusal of spaces indents (or mix)?
>>
>
> Because mixing spaces and tabs is often ugly.
I agree
> 8 spaces and a
> single tab often do not have the same width when you're viewing
> the text in a variable width font.
>
> I've read all my mail in a variable width font for over a decade, at
> first to watch for regressions in the XEmacs display engine, but I
> continued because I liked it. I presume I'm not the only one doing
> so.
>
>
Did not think anyone would read code with variable-sized font. :) In
such case the 80-rule is of little use when it comes to readability.
But do you not think there is people with small screens (and perhaps an
increasing number with the use of PDAs and smartphones), who would like
to change the tab-size to fit a small window (recall someone talking
about a 62 character wide screen), where a change from 8 to 2 gains 18
characters in just 3 levels.
In those cases, an only-used-as-indent-character is most preferable.
Of course, there is little point in patching existing tab-alignments,
but even less creating them, which checkpatch.pl like to do sometime,
with its "tabs not spaces".
cheers
Richard Knutsson
On 2/27/08, Randy Dunlap <[email protected]> wrote:
> I would gladly NAK it, but most recent email from Linus about
> coding style is that we are getting too detailed about it,
> so unless there is some overwhelming need to change anything in
> CodingStyle, I'm for no changes (or maybe even some removals).
Amen!
CodingStyleForDummies is long overdue...
Richard Knutsson <[email protected]> writes:
> In those cases, an only-used-as-indent-character is most preferable.
It is. The problem is that the editors can't do it (yet?). Or am I
mistaken?
--
Krzysztof Halasa
Krzysztof Halasa <[email protected]> wrote:
> Richard Knutsson <[email protected]> writes:
>> In those cases, an only-used-as-indent-character is most preferable.
>
> It is. The problem is that the editors can't do it (yet?). Or am I
> mistaken?
joe/jstar can, by keeping the whitespace from the previous line.
On Mar. 01, 2008, 0:34 +0200, Krzysztof Halasa <[email protected]> wrote:
> Richard Knutsson <[email protected]> writes:
>
>> In those cases, an only-used-as-indent-character is most preferable.
>
> It is. The problem is that the editors can't do it (yet?). Or am I
> mistaken?
"Yet" is the right answer :)
When creating a new line copying the indentation from the line above
and potentially filling more spaces as needed, according to
parenthesis or operators on the previous line should do the trick.
Benny
Benny Halevy <[email protected]> writes:
> When creating a new line copying the indentation from the line above
> and potentially filling more spaces as needed, according to
> parenthesis or operators on the previous line should do the trick.
Which editor and settings?
--
Krzysztof Halasa
On Mar. 03, 2008, 23:08 +0200, Krzysztof Halasa <[email protected]> wrote:
> Benny Halevy <[email protected]> writes:
>
>> When creating a new line copying the indentation from the line above
>> and potentially filling more spaces as needed, according to
>> parenthesis or operators on the previous line should do the trick.
>
> Which editor and settings?
no-one I'm aware of _yet_.
I'll take a stab at doing this on xemacs...
Benny