back to article Linus Torvalds in sweary rant about punctuation in kernel comments

Linus Torvalds has unleashed a sweary rant on the Linux Kernel Mailing List, labelling some members “brain-damaged” for their preferred method of punctuating comments. “Can we please get rid of the brain-damaged stupid networking comment syntax style, PLEASE?” the Linux Lord asked last Friday. “If the networking people cannot …

Silver badge

Linus must be running out of things to do!

38
5

My thought exactly...

I actually feel quite good when I see things like this going on. Because clearly, if the formatting of comments is the biggest problem in the Linux kernel, then it much be in pretty fantastic shape.

53
5
Trollface

Re: My thought exactly...

On the other hand, it may be irreparably broken and nobody can think of anything constructive to do...

14
7

This post has been deleted by its author

Silver badge

The New Defacto POSIX

> Because clearly, if the formatting of comments is the biggest problem in the Linux kernel, then it much be in pretty fantastic shape.

Yeah its PID 1 that is the total clusterfsck in Linux land. Unless you own lots of Red Hat stock then everything is so bright you have to wear shades.

7
3
Anonymous Coward

Still not finished the Linux kernel yet?

Can't finish a simple software project?

Geesh...

3
0
Silver badge

Re: My thought exactly...

>On the other hand, it may be irreparably broken and nobody can think of anything constructive to do...

If the Cthulhu like hairball that was OpenSSL can be saved virtually any code base can be with enough effort. The one exception that immediately comes to mind (besides some I have seen in private industry) is Netscape 4.7.2. Never seen a non 3D user land app with just regular user permissions crash an IRIX box before it. No surprise that they open sourced it in desperation (one of the first closed to open source commercial products) and the code was almost immediately thrown out.

2
0
Silver badge

Well, he did say "please" ...

20
0
Silver badge

The dumb fuck also agreed to multiple different styles, just not "those ones". If you want consistence don't allow more than two options:

In any case the multiline c-style with /* */ is particularly egregious especially when used inside amn indented block, and should not be allowed in new code.

5
33

I like the bit where you call the inventor and maintainer-in-chief of one of the most popular OS kernels on the planet a "dumb fuck".

18
4
Silver badge
Boffin

I tend to see a lot of "scientific" code, and I am typically too far over the moon if there are comments in there AT ALL that I am quite tolerant about the format, especially if the comments actually make sense.

33
0
Silver badge

Oh gosh a fanboi without a clue. The inventors were Ken Thompson and Dennis Ritchie. Linux is a clone of their work.

4
26

"Oh gosh a fanboi without a clue."

Was that in reply to me, John?

I'm well aware of Linux's history and that it is a *nix clone. But Linus did write his kernel from scratch, or as close as, which is a pretty hard thing to do - as is maintaining it. In your quest for pedantry on what you thought was my point, you rather missed my point...

7
1

Ditto. I worked for a genetics research company that employed several Slavic geniuses (no sarcasm). No one else touched the "Russian" code because it was indecipherable. They probably felt cramped by non-Cyrillic character sets limiting their options for single character variable names.

2
0
Anonymous Coward

Cyrillic is not so bad, not so many characters. Reasonably easy to learn the characters phonetically, if rather more work to learn vocabulary that isn't just loanwords or cursing!

0
0

How about PEP8 like guidelines on source-code checks before accepting a patch?

From Scratch? I guess I heard wrong. I thought his key addon was to add demand-paging rather than swapping - starting from the Minix kernel - which had previously been verified by AT&T as not using any of their UNIX code base (as they no longer wanted Tanenbaum using AT&T code in his books and lectures).

I frown on some of the language used in some of the reactions, but some people seem to have a limited vocabulary. However, I do believe - as was mentioned earlier - that specifying a specific style for comments (max of two - okay, but better: one format for single line, one format for multi-line).

One of the things I am finding hard to learn - but do appreciate - is the PEP 8 guidelines for python code. And, perhaps the Linux-kernal is ready for a "pep8"-like beautifier - or maybe just update 'beautify' to what will pass - and identify 'nonsense' (as I would agree that 'wasting' time to write a program to '*' align comments, or worse - doing it manually) does not improve the content (aka quality) of the comment(s).

0
0
Silver badge

Well there is a point to this

Code primarily is read by humans, and in fact comments are more commonly read than the actual code. So it makes sense to improve their readability.

And those are tiny things, but they are probably defined in some style document everyone touching the kernel should have read. It's a common argument that if someone doesn't even care about such small things, they probably haven't read the rules. It's like with that band that, somewhere in their specifications, had the rule that there had to be a bowl of m&ms, but no blue ones. If they found blue m&ms, they knew that their specifications were not read properly.

Just like with a concert, where a problem with the strength of a stage can lead to disaster, problems in the Linux kernel can be highly problematic.

45
4
gv

Re: Well there is a point to this

In my experience, you read the comments and then realise that the comments have little or no bearing on the actual code...

25
1
Silver badge

Re: Well there is a point to this

"In my experience, you read the comments and then realise that the comments have little or no bearing on the actual code..."

Well then you have mostly looked at bad code. Kernel code must be of higher quality than userspace code as errors in it can bring down the whole system either by crashing or by security problems.

23
2
Anonymous Coward

Re: Well there is a point to this

"Kernel code must be of higher quality than userspace code as errors in it can bring down the whole system either by crashing or by security problems."

Or as we like to call it - Linux

15
14
Coat

Re: Well there is a point to this

It was Van Halen.

http://sevenstorylearning.com/creativity/brown-mm/

6
1
Anonymous Coward

Re: Well there is a point to this

Well, I hope no drug-addicted-rocker-developer will ever ask me to write comments without using some letters....

0
6
Silver badge
Meh

Re: Well there is a point to this

That depends on the comments. I prefer to write code that just doesn't need them but Kernel code has to be performance and size oriented so that would be a lot more difficult unless the compiler is very, very good.

8
18
Silver badge
Boffin

Re: Well there is a point to this

It's interesting that some people don't like my idea of avoiding comments. You might find this article interesting at it sums up my view.

But to my mind it's fairly simple. If you feel the need to explain what your code is doing consider re-writing it.

An explanation of 'why you're doing it' is often useful and is fine. It's the plethora of 'what you're doing' that I dislike. They so often get out of date and are so often an excuse for poorly written code.

17
21
Silver badge

Re: Well there is a point to this

"Or as we like to call it - Linux"

And then realised we'd confused Linux with Windows.

5
5
Silver badge
Boffin

Re: Well there is a point to this

Uhm, I raise you this one, particularly the method next() in partition-asc-subset-lex.h (this is an O(1) algorithm for integer partitions). Even with comments it is not easy to understand. Without comments? Good luck.

I have regretted not pedantically commenting my own code more often than I care to admit. The visualstudiomagazine.com article is IMO close to bonkers.

19
2
Silver badge

Re: Well there is a point to this

"In my experience, you read the comments and then realise that the comments have little or no bearing on the actual code..."

No comment.

7
0

Re: Well there is a point to this

Looks like you're getting downvoted despite your point being valid AndrueC.

One thing I would say is that it probably isn't always true for something as complex as core kernel/driver code, which is always going to be pretty hairy in places. Applications code on the other hand, there's no excuses.

5
4

Re: Well there is a point to this

Sometimes, it is nice to write the tightest, most obscure code possible. Knowing, as you do so, that you will not have the slightest idea what the hell it actually does within two weeks time.

A 'work of art' snippit that should have been done in ASM, or INTERCAL, and you think 'job security' of sorts.

And later, so much later, find this little code calttrop with the simple comment:

// don't change this part

And wonder, "What the hell was I thinking?"

We did this all the time at my last shop.

14
0
Silver badge

Re: Well there is a point to this

"// don't change this part

And wonder, "What the hell was I thinking?""

I have written in the past, to myself

/* Don't change this. You think it isn't right, but it is.

I've thought about it a lot recently, and it is right.

I know what you are thinking: you're thinking it should

be n+1 rather than n, but it shouldn't be, it should be n.

I mean it. If you do, you will get the wrong answer. */

(Note the use of Linus-approved commenting.)

13
0

Re: Well there is a point to this

<snip>

"But to my mind it's fairly simple. If you feel the need to explain what your code is doing consider re-writing it."

<snip>

When I was writing code back in the day, my comments were mainly there for the next man who would be looking at the code. I have an almost autistic / lateral way of thinking and arriving at solutions. The next man on would probably have a more 'normal' way of doing things in a more serial manner. Comments would aid him to understand my twisted logic.

As a great Irish Philosopher and drunk called Brendan Behan once said;

"Every cripple has his own way of walking"

14
2
Anonymous Coward

Re: Well there is a point to this

"In my experience, you read the comments and then realise that the comments have little or no bearing on the actual code..."

And this is why comments should be included in the code review. They should be up-to-date and not just a re-iteration of what the code *IS* doing (we can see the code, we can see what it is doing) but *WHY* is it doing it. Why "userFullname" and not "userShortname"? What does a null response mean? Where is the spec to be found? etc

if the code needs a comment to say what it is doing (e.g. it's doing some mental bitwise guff) and there's no good reason for it (i.e. performance) then you take the comment out and re-write the code. Maintainable code is way, way more important than showing off.

Also part of the code review is logging. Give an example log to someone unfamiliar with the code. If they can't figure out what is happening, the logging needs to be re-done. You'll thank me when a "Production Down" event happens and all you have is a single log file + 1 hour to resolve before the contractual penalties start.

15
0
Anonymous Coward

Re: Well there is a point to this

If you have written nice straightforward code that is not too "clever", then another developer hunting down a bug should easily be able to work out what it does.

The purpose of the comment is to explain what your code is intended to do.

The developer can then compare what your code is trying to do with what it actually does and decide whether you have cocked it up.

8
0
MJI
Silver badge

Re: Well there is a point to this

Soemtimes code which you fully understand when written make no sense a year later when you are modifying it.

I prefer to write the comments then add the code in afterwards.

13
0
Silver badge

Re: Well there is a point to this

But to my mind it's fairly simple. If you feel the need to explain what your code is doing consider re-writing it.

A worthy aspiration but sometimes you need to structure code for performance rather than readability - and in those cases, comments are useful

14
0
Silver badge
Coat

Re: Well there is a point to this @Anonymous Blowhard

// No comment

FTFY!

4
0
Silver badge
Mushroom

Re: Well there is a point to this

Even with comments it is not easy to understand. Without comments? Good luck.

So use comments then!

Neither I nor that article have said that you shouldn't use them. We're just saying that you should consider rewriting the code as an alternative. In my original post I made the observation that kernel code likely would need commenting because by it's nature it was harder to write clear code. In my second post I just said you should consider rewriting code. Clearly you've come up with another example where it's hard to write code that is self-documenting.

Are you incapable of thinking in a nuanced way? That author clearly encountered people like you when he published his first article. You appear to have had a knee-jerk and polarised reaction and decided to pigeon hole me as never commenting my code.

At no *censored* time have I ever suggested that

All we're saying is that comments can create various problems and in a lot of cases they are not actually solving a problem. The best code is code that is self-explanatory and in my opinion every time you feel the need to write a comment you should at least take a minute and consider if the code could convey that information on its own. That's all. If the answer is 'no, it can't' then by all means use comments!

6
7
Silver badge
Facepalm

Re: Well there is a point to this

To be honest having come out of a meeting I'm now concerned about some of my fellow commentards. Maybe I'm expecting too much (and heck, it's not like commenting on El Reg articles matters) but could you perhaps at least try and read posts more carefully?

Several of you have pointed out that sometimes it isn't possible to rewrite code to avoid comments. Did you not notice that I accepted that in both my posts? The last half of my very first post is:

"but Kernel code has to be performance and size oriented so that would be a lot more difficult unless the compiler is very, very good."

Right there in writing is my acknowledgement that you can't always avoid writing comments. Sheesh - I hope you guys pay more attention when you're reading comments than you do when reading forum posts.

4
8
Silver badge
Stop

Re: Well there is a point to this

Well let me put it to you like this.....

"There's a way to communicate an opinion"

or

"There's a way to fucking communicate an opinion you fucking dangleberry! "

Difficult to respect *anyone* that communicates the way he seems to.

10
1
Silver badge

Re: Well there is a point to this

"Code primarily is read by humans, and in fact comments are more commonly read than the actual code. So it makes sense to improve their readability."

Coding style guidelines are (generally) a good idea. it makes things consistent and easier to visually scan. I suppose 'comment style' could just be part of that.

If you use Doxygen, following Linus' comment block style recommendations 'just works'.

When it comes to formatting the actual CODE, however, I have little respect for people who _INSIST_ on K&R style bracing, and believe that 'Allman Style' yields the MOST readable code. (/me ducks to avoid flying objects). Then there's the practice of using hard-tabs for indenting, which ALSO needs to "just go away" (/me ducks again). That way you can use 'cat' and 'less' to view source files in a Linux console, and they'll appear CONSISTENT with what you see in an editor.

(I also do banners with 'figlet' and a shell script that puts a nice 'right-hand edge' on them, centering the text, sticking a copyright statement underneath the banner, yotta yotta - let the script do the right-hand edge and you don't have to fiddle with it)

4
3
Silver badge
Pint

Re: Well there is a point to this

You seem to be perplexed/annoyed with downvotes similar to me.

Have an upvote and a pint ------------------------->

As you may seen from the snipped I linked to I am in HPC and discrete mathematics. If I do not comment my code really carefully I may just delete it when done. There is little chance I understand it myself even weeks later, as I learned the hard way.

Even if I find something simple to understand, I tend to comment out of courtesy to the potential reader.

Also, I have spotted bugs in the process of "just" putting comments.

7
1
Silver badge
Headmaster

Re: Well there is a point to this

> Allman Style

Yes. And to hell with GNU style!

> ...hard-tabs for indenting, which ALSO needs to "just go away"

Indeed! Aaaaaand indent should be 4, not 8.

4
1
Silver badge
FAIL

@DavCrav -- Re: Well there is a point to this

Well congratulations! You've just written a very detailed comment that is not one fucking bit better than the code it purports to elucidate. Lots of ratchet-jawing about "do this, don't do that", but not one syllable as to why we think it should be n+1 when it is really supposed to be n.

Don't dislocate your shoulder patting youself on your back.

3
0
Silver badge

Re: Well there is a point to this

"When I was writing code back in the day, my comments were mainly there for the next man who would be looking at the code. "

This.

You may be a fantastic coder who can look at a function in FORTRAN and instantly divine it's purpose, or you may just have a great memory and recall why you wrote every bit of code as you did. Regardless, assume the next guy who's going to look at it is a half-blind concussed chimpanzee in a masturbatory frenzy with an attention span of 45 seconds, knows nothing of the language and will delete anything that is not explicitly commented with 'DO NOT DELETE THIS YOU PILLOCK'.

We know for a fact that, no matter how short-term code is meant to be in use for, there are many cases critical for the functioning of the entire economy where bits of code have actually outlived the languages they're written in. Dead languages lurk at the bottom of banks and underlying the nuclear weapons launch systems. In fifty years, some poor bastard who only heard of C++ once in a two-hour history lesson while he was hung over may need to crack open your code and figure out what the hell it is meant to do on a time limit, and if you're not commenting because of some idiotic notion of 'coding purity' or some other bullshit, then that guy's life just became infinitely harder. Comment properly, don't be an asshole.

Besides, writing code 'clearly' is often the exact opposite of writing code efficiently.

9
1
Silver badge
Trollface

Re: Well there is a point to this

RE: ". I prefer to write code that just doesn't need (comments)"

Is that even possible in C++ ?

6
0
Silver badge

Comments are a pain to write

It's a lot easier to add all the comments all at once by copying them from random open source code. Doing it all at once minimizes the time spent working on comments as well as the time spent checking in code from other people's desks.

1
0
Silver badge
Happy

Re: Well there is a point to this

> ...hard-tabs for indenting, which ALSO needs to "just go away"

Indeed! Aaaaaand indent should be 4, not 8.

Tab doesn't have to be 8 spaces. Just saying.

2
1

Re: Well there is a point to this

I think string makes the key point, here: almost by definition, things like driver code can't be self-documenting, because it's dealing with an external blob of hardware that will do weird things that are (hopefully) described in some massive ICD. So while we're all well aware that code with side effects is normally frowned upon, the whole point of driver code is that it has side effects.

1
0
JLV
Silver badge
Thumb Down

Re: Well there is a point to this

>drug-addicted rocker

Judgmental much?

David Lee Roth comes across as quite clever, and witty, on the M&M explanation video. Probably someone I'd respect if I had to work for him.

2
0
Silver badge

Re: Well there is a point to this

Re: It was Van Halen.

But did that and other similar clauses appear in the contract before or after Eddie Van Halen knocked himself out after enthusiastically leaping off the drum kit and head butting a mirror ball?

0
0

Page:

POST COMMENT House rules

Not a member of The Register? Create a new account here.

  • Enter your comment

  • Add an icon

Anonymous cowards cannot choose their icon

Forums

Biting the hand that feeds IT © 1998–2017