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 …

  1. Sorry that handle is already taken. Silver badge

    Linus must be running out of things to do!

  2. Edwin

    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.

  3. James Howat
    Trollface

    Re: My thought exactly...

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

  4. This post has been deleted by its author

  5. asdf 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.

  6. Anonymous Coward
    Anonymous Coward

    Still not finished the Linux kernel yet?

    Can't finish a simple software project?

    Geesh...

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

  8. allthecoolshortnamesweretaken Silver badge

    Well, he did say "please" ...

  9. John Lilburne 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.

  10. Olius

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

  11. Michael H.F. Wilkinson 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.

  12. John Lilburne Silver badge

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

  13. Olius

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

  14. Prof. William Waterman Sherman

    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.

  15. Anonymous Coward
    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!

  16. Michael Felt

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

  17. Christian Berger 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.

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

  19. Christian Berger 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.

  20. Anonymous Coward
    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

  21. Hud Dunlap
    Coat

    Re: Well there is a point to this

    It was Van Halen.

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

  22. Anonymous Coward
    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....

  23. AndrueC 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.

  24. AndrueC 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.

  25. Doctor Syntax 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.

  26. GrumpenKraut 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.

  27. Anonymous Blowhard

    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.

  28. string

    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.

  29. John F***ing Stepp

    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.

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

  31. Bloakey1

    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"

  32. Anonymous Coward
    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.

  33. Anonymous Coward
    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.

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

  35. Hans Neeson-Bumpsadese 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

  36. VinceH Silver badge
    Coat

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

    // No comment

    FTFY!

  37. AndrueC 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!

  38. AndrueC 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.

  39. IsJustabloke 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.

  40. bombastic bob 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)

  41. GrumpenKraut 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.

  42. GrumpenKraut 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.

  43. Someone Else 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.

  44. Naselus 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.

  45. Geoffrey W 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++ ?

  46. Nolveys 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.

  47. Down not across
    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.

  48. Malcolm Weir Silver badge

    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.

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

  50. Roland6 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?

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

Biting the hand that feeds IT © 1998–2018