[PATCH] coding-style.rst: indentation: Clarify tabs text

[PATCH] coding-style.rst: indentation: Clarify tabs text

[Bru Moreira-Guedes]

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

The old text about tabs failed to clearly convey the message that the
TAB character is used for indentation. It also gives the misleading
impression that it's trying to "redefine" what a tab (the 0x09 ASCII
character) is when it says "tabs are 8 characters".

It might be misleading, especially for some autistic readers for whom
English is not the first language and whose tendency to interpret things
more literally might be present (i.e., my very own self).

The present patch clarifies the tabs text on such aspects.

Signed-off-by: Bru Moreira-Guedes <codeagain@codeagain.dev>
---
 Documentation/process/coding-style.rst | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 007e49ef6cec..9a0205fa7ed3 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -18,23 +18,25 @@ Anyway, here goes:
 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 Linux Kernel uses the TAB character for indentation, as in the K&R
+style. Tabs are meant to be viewed as 8-characters, and thus
+indentations are meant to be seen as 8 characters as well. There are
+heretic movements that try to use spaces for indentation, or make tabs
+viewed as 4 (or even 2!) characters, and that is akin to trying to
+define the value of PI to be 5.
 
 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.
 
-Now, some people will claim that having 8-character indentations makes
+Now, some people will claim that viewint 8-character tab 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-char tab size make things easier to read, and have the added
 benefit of warning you when you're nesting your functions too deep.
 Heed that warning.
 
-- 
2.39.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH] coding-style.rst: indentation: Clarify tabs text

[Bagas Sanjaya]

On 3/1/23 05:20, Bru Moreira-Guedes wrote:
> It might be misleading, especially for some autistic readers for whom
> English is not the first language and whose tendency to interpret things
> more literally might be present (i.e., my very own self).
> 

I'm also actually autistic (∞) :) ...

> The present patch clarifies the tabs text on such aspects.
> 

Clarify tabs description?

> -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 Linux Kernel uses the TAB character for indentation, as in the K&R
> +style. Tabs are meant to be viewed as 8-characters, and thus
> +indentations are meant to be seen as 8 characters as well. There are
> +heretic movements that try to use spaces for indentation, or make tabs
> +viewed as 4 (or even 2!) characters, and that is akin to trying to
> +define the value of PI to be 5.
>
  
"In the context of kernel code, tabs are intended to be 8-characters
indentation."

>  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.
>  
> -Now, some people will claim that having 8-character indentations makes
> +Now, some people will claim that viewint 8-character tab indentations makes
viewing

>  
> -In short, 8-char indents make things easier to read, and have the added
> +In short, 8-char tab size make things easier to read, and have the added

8-char tab indents (for consistency with above)?

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH] coding-style.rst: indentation: Clarify tabs text

[Jonathan Corbet]

Bru Moreira-Guedes <codeagain@codeagain.dev> writes:

> The old text about tabs failed to clearly convey the message that the
> TAB character is used for indentation. It also gives the misleading
> impression that it's trying to "redefine" what a tab (the 0x09 ASCII
> character) is when it says "tabs are 8 characters".
>
> It might be misleading, especially for some autistic readers for whom
> English is not the first language and whose tendency to interpret things
> more literally might be present (i.e., my very own self).
>
> The present patch clarifies the tabs text on such aspects.
>
> Signed-off-by: Bru Moreira-Guedes <codeagain@codeagain.dev>
> ---
>  Documentation/process/coding-style.rst | 14 ++++++++------
>  1 file changed, 8 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> index 007e49ef6cec..9a0205fa7ed3 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -18,23 +18,25 @@ Anyway, here goes:
>  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 Linux Kernel uses the TAB character for indentation, as in the K&R
> +style. Tabs are meant to be viewed as 8-characters, and thus
> +indentations are meant to be seen as 8 characters as well. There are
> +heretic movements that try to use spaces for indentation, or make tabs
> +viewed as 4 (or even 2!) characters, and that is akin to trying to
> +define the value of PI to be 5.

I guess I really don't see how this kind of tweaking helps things; this
text has stood for a couple of decades or so without evident
misunderstandings.

...and I'm totally mystified as to why we've redefined pi from 3 to 5?

>  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.
>  
> -Now, some people will claim that having 8-character indentations makes
> +Now, some people will claim that viewint 8-character tab indentations makes

Adding typos doesn't really help either.

Thanks,

jon

Re: [PATCH] coding-style.rst: indentation: Clarify tabs text

[Bru Moreira-Guedes]

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

Hello, Jonathan!

(Resending for I accidentally didn't copy the lists)

On Tue, Mar 07, 2023 at 10:13:44AM -0700, Jonathan Corbet wrote:
> Bru Moreira-Guedes <codeagain@codeagain.dev> writes:
>
> > It might be misleading, especially for some autistic readers for whom
> > English is not the first language and whose tendency to interpret things
> > more literally might be present (i.e., my very own self).

Perhaps I clearly made a poor description of the problem this patch
solves. I'll address it in details when I respond to your points. I
could certainly improve it for a v2.

> >
> > The present patch clarifies the tabs text on such aspects.
> >
> > Signed-off-by: Bru Moreira-Guedes <codeagain@codeagain.dev>
> > ---
> >  Documentation/process/coding-style.rst | 14 ++++++++------
> >  1 file changed, 8 insertions(+), 6 deletions(-)
> >
> > diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> > index 007e49ef6cec..9a0205fa7ed3 100644
> > --- a/Documentation/process/coding-style.rst
> > +++ b/Documentation/process/coding-style.rst
> > @@ -18,23 +18,25 @@ Anyway, here goes:
> >  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 Linux Kernel uses the TAB character for indentation, as in the K&R
> > +style. Tabs are meant to be viewed as 8-characters, and thus
> > +indentations are meant to be seen as 8 characters as well. There are
> > +heretic movements that try to use spaces for indentation, or make tabs
> > +viewed as 4 (or even 2!) characters, and that is akin to trying to
> > +define the value of PI to be 5.
>
> I guess I really don't see how this kind of tweaking helps things; this
> text has stood for a couple of decades or so without evident
> misunderstandings.

Well, there was my own misunderstanding that motivated this patch :-}
so, there is at least one evidenced case. Anyway, I think this is more
of an improvement to make the text accessible for everyone, including
autistic readers who might have a tendency towards literal
interpretation. Just like me :D

I don't actually think we would have a way to find out if everyone else
who read this text throughout all those decades got it properly.
Historically, the linux kernel hasn't been overall a much accessible
project in a general sense. I think this kind of change is important if
we want to move to the right direction.

> ...and I'm totally mystified as to why we've redefined pi from 3 to 5?

Ohhh, never mind this part, it shouldn't be here. At first I was
undecided on whether to change it or not. I actually thought I had
removed it. It just came to my mind that the value of pi is a constant,
yet its representation is always bound to a certain precision level.
Since the text didn't use decimal places, assuming no decimal precision
the pi is actually near 3. Since the text appears to be trying to show
an example of something "absurd", I think another value could be more
appropriate. But yea, this change would not affect anyone and I think it
shouldn't be done.

> >
> > -Now, some people will claim that having 8-character indentations makes
> > +Now, some people will claim that viewint 8-character tab indentations makes
>
> Adding typos doesn't really help either.

Sorry, I clearly had a poor review of the changed text (and I failed to
setup spell-checking on checkpatch.pl). Yet Bagas did an excellent job
in the other thread pointing me out all the details I missed. I'll be
doing a v2 soon!

Best,
Bru Moreira-Guedes
they/them


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]