
Linux kernel coding style - e19293001
https://01.org/linuxgraphics/gfx-docs/drm/process/coding-style.html
======
nolemurs
Other people are complaining about the 80 character line limit, but
personally, I'm shocked and dismayed by the preference for no braces on `if`
statements with single line blocks. It is _so_ easy to accidentally add a line
to what looks like an `if` block (but isn't since there are no braces), and
then you have a bug that is visually very difficult to spot. I'm pretty
strongly against this rule!

~~~
byllgrim
I don't get what "what looks like an `if` block" is. In a no-brace if, the
statement that follows is indented. The next line after that is not indented.
So the indented statement obviously belong to the if.

~~~
nolemurs
The issue that comes up is when you go to add a line to that 'block' it's easy
not to notice that it's not actually a block, just a single statement. Then
you add another indented line, and now you've got something that looks a _lot_
like a block, but isn't at all!

Of course, as others have pointed out, with some sort of reasonable linting
setup or with compiler warnings, you'll probably catch the bug (unless macros
are involved), but even so, I feel having something that looks like a block
but isn't, adds cognitive load for little benefit.

------
danilocesar
2017 and contributors still need to discuss about coding style =/

If you want to enforce codding style (which is OK) you need to provide
developers the tools to ease that process.

Contributing with patches to 15 different projects, using 15 different rules
for styling makes it impossible to keep up.

FOSS projects should start using tools like clang-format so developers don't
need care if a project use 2/4/6/8 spaces instead of tab. The tool should be
able to automatically format the code before committing.

Some projects even use git hooks to compare the commit with auto-generated
styling tools to check if it follows the rules.

~~~
dpcx
Sure, it's difficult for a committer to keep up with all of the different
styles. Imagine being a developer on a project with 50 different committers,
all doing it their own way.

As a committer, I would rather have it clearly explained what the rules are
_before_ I do it incorrectly. Sure, having tools that will do it for me is
awesome, but considering how many examples in the OP are different because of
historical reasons, those tools are difficult to configure.

~~~
danilocesar
> Sure, it's difficult for a committer to keep up with all of the different
> styles. Imagine being a developer on a project with 50 different committers,
> all doing it their own way.

That's exactly what tools like clang-format fixes. Code will be in the
repository using one correct styling. The difference is that the commiter
won't have to style it himself.

> As a committer, I would rather have it clearly explained what the rules are
> before I do it incorrectly. Sure, having tools that will do it for me is
> awesome, but considering how many examples in the OP are different because
> of historical reasons, those tools are difficult to configure.

Which tools you said that are difficult to configure? clang-format? It's 5~20
lines in a .clang-format in the root folder of your repo. Configure it once
and profit forever.

* I'm talking about clang-format here because that's what I use for C/C++. I don't know anything about other languages.

~~~
dpcx
How well does clang-format handle subfolders with their own rules? I don't
know, as I'm not a C/C++ developer; but I know that the tools I use don't
handle them very well. I still provide them, of course, because it's better
than nothing.

------
nunofgs
Only thing I really don't agree with is the 80 char max.

I'm not suggesting unlimited but isn't it time we revisit this?

It really feels like one of those "we've always done it this way so just leave
it"

~~~
kornish
As someone who routinely has 5 or 6 files open in various configurations of
Emacs windows, 80 char max is a huge convenience. Out of interest, what's
changed since it became a norm which would make it worth reexamining?

~~~
paulddraper
Screen size. On my two 24 inch monitors, I can easily have four side-by-side
files with 100 characters and a large font size.

This being HN, naturally someone's going to tell me they do most of their
programming on a 7 inch terminal screen.

But 80 chars comes with a cost: over terse code, or a lot of scrolling.

~~~
Arizhel
Exactly, I do the same: dual 24-inch monitors with 4 windows, and a
100-character line limit.

------
terrywang
Indentation war is ON again ;-)

TL;DR - Linux kernel source code use TABs (8 characters) instead of spaces.
The rationale behind is that the maintainers believe that large indentation
makes code easier to read on screen (especially for long hours), makes sense.

Personally I (not a programmer but Linux SysAdmin/Ops/Infra Architect
background) tend to use 4 spaces everywhere else (e.g. Shell, Ruby, Java and
all sorts of configuration files). Not to pick a fight (sounds familiar? ;-)
but 2 spaces in general make readability worse.

Anyway, the most important point is to honour what is already established/in
place and stick to it, whatever you work on.

~~~
tiglionabbit
People should just use actual tabs. Then you can make the indentation display
however you want in your editor. And you never have to worry about deleting
part of an indent level, creating weird slightly offset indentations.

I know, everyone is going to downvote me for saying this. But if you're
literally using 8 spaces to represent a tab, which is the default width tabs
are rendered at, then what downside could there be to switching to actual
tabs?

Edit: "spaces are never used for indentation" so do they actually use tab
characters then?

~~~
aanm1988
> In all cases, prefer spaces to tabs in source files. People have different
> preferred indentation levels, and different styles of indentation that they
> like; this is fine. What isn’t fine is that different editors/viewers expand
> tabs out to different tab stops. This can cause your code to look completely
> unreadable, and it is not worth dealing with.

from the LLVM style guide.

~~~
tiglionabbit
What's an example of some source code that becomes unreadable when you change
the size of tabs? Are you editing code in Microsoft Word or something? Setting
custom tabstops and shooting yourself in the foot?

Don't mix tabs and spaces in indentation btw. That is the one thing you must
never do.

~~~
stouset
Tabular alignment is practically the one thing of all these holy wars that
_actually improves readability_. So no, that's not something funny — it's
something that trivially and immediately improves readability of your source.

    
    
        foo = 1;
        this_value_is_not_foo = 8;
        another_int = 419;
        pi = 314159;
    

versus:

    
    
        foo                   =      1;
        this_value_is_not_foo =      8;
        another_int           =    419;
        pi                    = 314159;

~~~
mcbits
This gives the false impression that the variables are all related. If they
are related, they should probably be encapsulated in some kind of structure.
And once you add the comments explaining what the first three variables are
and how they should be used, and the comment explaining why pi doesn't have a
decimal point, there is no benefit to alignment. If you add another long line,
you have to realign the whole list (or leave it looking sloppy). Overall, this
kind of alignment is a bad idea.

~~~
stouset
Congratulations for taking my contrived example way too literally and missing
the point entirely.

Not every group of variable assignments warrants a comment for every line, nor
is my argument relevant only to static constants, nor is there any reason why
aligned assignments should be construed to be related any more than
consecutive assignments should be, nor should _that_ stop you from reaping the
unarguable improved readability of aligning them anyway.

------
corndoge
Have to agree with the comment on GNU coding style, I work on a project that
uses it and it really sucks. Braces on a newline and indented two spaces...

------
Trufa
Offtopic question, what documentation tool is used for this? I've seen it a
lot of times but I'm not sure how to search for it. Thanks!

~~~
geofft
It's made with Sphinx, a tool commonly used for Python documentation. But it
can render reStructuredText that isn't associated with Python just as well, so
it's popular for other projects. [http://sphinx-doc.org/](http://sphinx-
doc.org/)

(There's a link to Sphinx at the bottom of the page)

It looks like this is just generated from Documentation/index.rst and linked
pages in the kernel source tree, which seems to have been created less than a
year ago:
[https://github.com/torvalds/linux/commits/master/Documentati...](https://github.com/torvalds/linux/commits/master/Documentation/index.rst)

~~~
mook
For background on the docs in the kernel source tree, LWN (as is often the
case) had a good article about it:
[https://lwn.net/Articles/692704/](https://lwn.net/Articles/692704/)

There's also a copy on kernel. org, not sure why Intel's copy is being linked
here. It's probably the same text, so any copy should be equally good, it just
feels less canonical to me. Probably silliness on my part for even thinking of
it.

~~~
geofft
Oh, hey, there's a rendered copy at
[https://www.kernel.org/doc/html/latest/process/coding-
style....](https://www.kernel.org/doc/html/latest/process/coding-style.html) ,
neat! (I knew about the unrendered one at /doc/Documentation)

------
skybrian
It seems like sensible advice but with gratuitous insults interspersed, just
to make sure you're really clear that the natives are not friendly.

~~~
mackal
You're right, humor should be illegal.

------
sverige
The writing style of this document seems somewhat casual ("Please at least
consider the points made here.") and a little confusing compared to OpenBSD's
style guide. [1]

The LibreSSL team spent months putting the OpenSSL code into KNF. It makes a
big difference, even though it may seem trivial.

[1] [http://man.openbsd.org/style](http://man.openbsd.org/style)

------
geofft
This is from Documentation/process/coding-style.rst (formerly
Documentation/CodingStyle) in the kernel source tree; an unrendered version is
canonically at [https://www.kernel.org/doc/Documentation/process/coding-
styl...](https://www.kernel.org/doc/Documentation/process/coding-style.rst)

------
hughes
What is K&R? It's referenced several times but not defined.

~~~
aanm1988
Kernighan and Ritchie, the C Programming Language.
[https://en.wikipedia.org/wiki/The_C_Programming_Language](https://en.wikipedia.org/wiki/The_C_Programming_Language)

------
s3arch
>First off, I’d suggest printing out a copy of the GNU coding standards, and
NOT read it. Burn them, it’s a great symbolic gesture.

Should I be aware of something from GNU coding standards?

~~~
sandov
2 spaces for indentation.

------
reynoldsbd
> Tabs are 8 characters...

The madman!

/s

Actually, now that I think about it, he has a point. Having a little more
horizontal space seems like it would be easier on the eyes.

~~~
tiglionabbit
Huh. Considering they also implement an 80 character limit to line length,
that could be a bit restrictive. Perhaps it means you have to refactor into a
function once you reach a certain depth of blocks. You can only really go 9
blocks deep.

I hate line length limits personally. Especially because I tend to use long
identifiers which eat up most of my line length limit in one go if you try to
utter them with their enclosing namespaces.

~~~
adrianratnapala
It's intended to be restrictive. The idea is that more than three levels of
indentation should be the exception rather than the rule. Exceeding that
without good reason is a hint that functions should be split up.

Having some such rough limit is a good thing, but the number 3 is language
dependent. Java for example automatically eats one level for the class.

Also C lacks syntax such as nested functions, try blocks, python-style context
managers and all kinds of other stuff which excuse more levels of indentation.

------
azaras
I like gofmt which avoids this problem in golang.

------
pyed
Coding style wars will die with the rise of *fmt.

~~~
belovedeagle
Okay, let us know when you've written a fmt which works on, say, a mere 70% of
kernel code. That should let you ignore the $N different assembler syntaxes at
least.

