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!

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

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

        1. This post has been deleted by its author

        2. asdf

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

        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.

    2. Anonymous Coward
      Anonymous Coward

      Still not finished the Linux kernel yet?

      Can't finish a simple software project?

      Geesh...

  2. allthecoolshortnamesweretaken

    Well, he did say "please" ...

    1. John Lilburne

      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.

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

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

          1. This post has been deleted by its author

            1. 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!

        2. John Lilburne

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

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

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

  3. Christian Berger

    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.

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

      1. Christian Berger

        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.

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

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

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

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

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

              1. 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!

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

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

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

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

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

              1. DavCrav

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

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

              2. Roland6 Silver badge

                Re: Well there is a point to this

                A 'work of art' snippit that should have been done in ASM, or INTERCAL,

                You can write some very obscure code in ASM. I remember having to write a piece of OS code that had to be shoehorned into a couple of dozen unused bytes remaining in a 4K PROM. I managed it, but not without making full use of some rather obscure, but documented (in the original Intel documentation and errata but not in third-party documentation), behaviours of the i8085 instruction set and flags register.

                From memory, the short section of code (<30 bytes) was spread across 4 sheets of 80 column fan fold, the remaining space was consumed by the comments that documented the multiple logic paths embedded in the code that were invisible to the casual reader. For those brave enough to actually visit the library there was also a few dozen A4 pages of algebra (checked by CAR Hoare), proving the logic of the code.

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

              1. Naselus

                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.

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

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

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

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

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

        1. VinceH
          Coat

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

          // No comment

          FTFY!

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

      4. Nolveys

        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.

      5. Captain DaFt

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

        Oh, Oh! You mean this one?

        /* I wrote this kludge because the boss said if the code wasn't ready to ship tomorrow my ass was fired. I'm starting a better job at a better company next month and I'd prefer to collect a paycheck until then. To whoever gets my job and has to maintain this --- May God have mercy on your soul! */

      6. nijam Silver badge

        Re: Well there is a point to this

        > the comments have little or no bearing on the actual code...

        Actually, since comments are for humans and code is for compilers, it's common for them to be unrelated. It's been said before of comments that "the best you can hope for is that they don't contradict the code".

    2. Hud Dunlap
      Coat

      Re: Well there is a point to this

      It was Van Halen.

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

      1. 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?

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

      1. JLV
        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.

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

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

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

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

        2. Anonymous Coward
          Anonymous Coward

          Re: Well there is a point to this

          4 ??? .... Are you insane?

          Everyone knows that 2 is the correct indent for any vaguely useful (a.k.a white-space sensitive) language.

          (N.B. This is a joke)

  4. Jeffrey Nonken

    For comments on lines of code, I prefer to use the double slash.

    For block comments I generally have a slash followed by a line of asterisks, followed by one or more lines of text (no asterisks), followed by a line of asterisks ending in a slash. Separates the block visually, nice symmetry, easy to edit.

    I'm sure Linus would find other reasons to hate me, if not that.

    We should all remember Nathan Hale's famous line, "I only regret that I have but one asterisk for my nation."

    1. Anonymous Coward
      Anonymous Coward

      Using lots of asterisks was a common habit on monochromatic terminals - before even text editors could color-syntax code. You need a way to easily tell what was code, and what was comment. Far less need today of "boxing" comments as they will be visualized in a different way.

      Unless you're a true Luddite and refuse to use any modern editor and use a syntax highlighter.

      1. Doctor Syntax Silver badge

        "Using lots of asterisks was a common habit on monochromatic terminals"

        Monochromatic terminals? Luxury! Kids, today! Don't know they're born! We used them with punched cards and fanfold. (I miss fanfold but cleaning out the "study" yesterday I discovered a whole box of it - but no music lines.)

        1. Triggerfish

          It's abacuses I have problems with. I always find it really fiddly tying the small knots on the bars to mark my comment section.

          1. Bloakey1

            "It's abacuses I have problems with. I always find it really fiddly tying the small knots on the bars to mark my comment section"

            Bloody kids of today. Abaci.

            Mumbles off left of stage mumbling about lack of Latin in school curriculum these days.

    2. Anonymous Coward
      Anonymous Coward

      Yep.

      The greater person learns and accepts others formats.

      That is, if Linux is so good at his work, could he not be a bit more polite in understanding the entire world is not the same as he is?

      I'm now tempted to put my comments in actual functional and exciting code now.

      1. Doctor Syntax Silver badge

        Re: Yep.

        "That is, if Linux is so good at his work"

        Who is this Linux of whom you write?

        1. GrumpenKraut
          Coat

          Re: Yep.

          Linux Torvalx?

          1. Fruit and Nutcase Silver badge
            Happy

            Re: Yep.

            @GrumpenKraut

            Linux Torvalx?

            That must be the new computer whiz-kid character in Asterix

        2. Bloakey1

          Re: Yep.

          "Who is this Linux of whom you write?"

          He was a character in Peanuts and he invented the Windows operating system to boot. Errr or perhaps not to boot if you are a Eunuchs <sic>users.

    3. MJI Silver badge

      Nathan Hale

      Funny but when I played Resistance Fall of Man I do not remember that comment

    4. bombastic bob Silver badge

      "I'm sure Linus would find other reasons to hate me, if not that."

      no doubt. A record of Linus' quirky antics would make a funny book.

      And I saw that Nathan Hale quote written like this once:

      "I only regret that I have but one * for my country"

      took me a while to figure out what the hell the '*' meant... and then the 'fridge moment' when the light came on.

      (As I recall, the '*' quote was on a 'Wretched Mess' calendar, which I don't think still exists in live print, but I google'd and saw a blog that mentioned it, and a books page for the author "Milford Stanley Poltroon" that had a few books about fishing with Monty-Python-worthy titles like 'The Happy Fish Hooker')

    5. Charles 9

      "For comments on lines of code, I prefer to use the double slash.

      For block comments I generally have a slash followed by a line of asterisks, followed by one or more lines of text (no asterisks), followed by a line of asterisks ending in a slash. Separates the block visually, nice symmetry, easy to edit."

      That's my style, too, and I tend to keep a certain structure. Each section of code (declarations, definitions, etc.) I use a simple block comment: Line, Section name in all caps, Line. Functions I use a detailed block quote that spells out what it's supposed to do, what goes in, what comes out.

      And the reason I use lots of comments is because I realize different people think in different ways. The path of logic I took to get something done may not be the same one someone else uses, and as result following actual code can sometimes derail people simply due to different experiences. Since I've personally had to go through the act myself with someone else's sparsely-commented code, I can speak from experience; it can be a slog, and many of us have deadlines. So the inline comments act like breadcrumbs to map out the paths within functions like the blocks act as signposts to show goals and other things in a broader sense.

    6. Brangdon

      re: For block comments

      In my view block comments of code need to have a marker at the start of each line so that when they appear without context, eg via grep or other search tools, it is still obvious it is a comment. That marker can be as asterix, I guess, but I just use // for all comments. My text edit makes it easy.

      I also let the text editor wrap long lines, so I only need one // per paragraph, making it easy to edit. Using hard line breaks is a bad idea when you are editing in a window that might not be exactly 80 columns wide.

  5. Steve Button Silver badge

    /* This is a comment *./

    Shoudn't that be

    /* This is a comment. */

    ?

    1. Anonymous Coward
      Anonymous Coward

      But for true artistry, it should be:

      /* This is not a comment. */

      Ah, the The Treachery of Comments.

      1. BongoJoe

        /* This comment left intentionally blank */

      2. billse10

        You might think that.

        You might very well think that.

        I could not possibly comment.

  6. Planty Bronze badge
    Mushroom

    Tabs vs Spaces

    Sounds just like tabs vs spaces argument. Perfhaps Linus has just watched silicon valley and he is being ironic???

    1. kmac499

      Re: Tabs vs Spaces

      May I humbly suggest a decent code editor with colour highlighting of reserved words etc,

      the option to reformat code, Sort functions alphabetically within scope ranges and user created tagged groups.

      Plus the option to add pre formattted skeleton comment headers to modules and functions...

      I can just about cope with poorly commented code; but if it's not load out to my personal choice of indent and blank lines I find it almost impossible to scan and get a feel for it's shape.

      1. werdsmith Silver badge

        Re: Tabs vs Spaces

        Writing a little parse module to run in the make, that would reformat comments shouldn't be beyond Linus' world.

      2. bombastic bob Silver badge

        Re: Tabs vs Spaces

        "May I humbly suggest a decent code editor with colour highlighting of reserved words etc,"

        pluma or gedit (prior to gnome 3) will do until I get my own IDE editor finished.

        sorting functions alphabetically, though... *shudder* [unless you name them deliberately by functionality].

  7. Dan 55 Silver badge

    Well it could be worse

    There could be no comments at all apart from stupid ones like "set i to 1" where they aren't necessary.

    Code review? Documentation? Yes, we've heard of them.

    1. Anonymous Coward
      Anonymous Coward

      Re: Well it could be worse

      Did you work with some of my colleagues too? <G>

    2. Tom 38

      Re: Well it could be worse

      I was once tasked to work on a library doing annoying statistical aggregation. It was last worked on about 5 years previously, and I swear to Cthulu, the only comments in the file were frequent occurrences of

      // modified by Cedric

      and occasionally

      // putain

      He never explained why he kept redefining his macro for doing malloc at various points throughout the 10k long file..

  8. Linker3000

    Linus Torvalds in sweary rant

    Must be a day with a 'y' in the name.

    1. Flocke Kroes Silver badge

      Re: Must be a day with a 'y' in the name.

      Not until tomorrow. Today is Boomtime, the 46th of Confusion 3182.

    2. NotBob
      Holmes

      Linus Torvalds in pointless sweary rant about something that doesn't matter

      FTFY

    3. Charles 9

      Re: Linus Torvalds in sweary rant

      "Must be a day with a 'y' in the name."

      Well, for someone living in a Spanish-speaking country, such a day doesn't exist. NONE of the weekdays have a 'y' in Spanish. Even the Spanish word for day (dia) doesn't have a y in it.

  9. Anonymous Coward
    Anonymous Coward

    Code Rage

    File names, directory names, tables, columns, variables, use of capitals, use of multiple capitals, comments. As I get older and crustier I am more and more convinced that I am always right, so just do it right people or you're gettin a feckin keyboard round yer mush.

    1. Doctor Syntax Silver badge

      Re: Code Rage

      I always insist on consistency. It's just that what I'm consistent with seems to change over time.

    2. 404

      Questions on the type of keyboard

      Would a $10 USB Logitech keyboard be acceptable*, or just to let them know you're serious, a PS/2 IBM keyboard**?

      *knowing it will be destroyed

      ** just hose off blood/hair, start project again.

      1. Anonymous Coward
        Anonymous Coward

        Re: Questions on the type of keyboard

        Don't be so sure. I once saw a person catch something like and, in one motion, without even looking up, send it back at the thrower.

  10. Anonymous IV

    Punctilious

    Remarkably apposite word in this circumstance!

    In faraway days long, long ago, when IBM used to provide to customers the code of their mainframe DOS/VS operating system on microfiche, and people actually used to read it, there was a complaint from a shocked and horrified manager who objected to the comment "Loop 1000 times, just for the hell of it". The next version of the OS showed a change to "Loop 1000 times".

    1. John F***ing Stepp

      Re: Punctilious

      There was a comment in MS DOS (2 I think) that went along the lines of 'if I had wanted you to use the damned /

      I would have told you'

      Those were the days when you booted up the machine with a floppy that looked as if it had been used as a frisbe and hoped.

      1. Bloakey1

        Re: Punctilious

        "There was a comment in MS DOS (2 I think) that went along the lines of 'if I had wanted you to use the damned /"

        <snip>

        I read this many moons ago. It was penned by an somebody decompiling DEC code due to poor documentation. He appeared to have been burning the candle at boths ends and the sides as well.

        Enjoy:

        * On the other hand, we never get another interrupt after

        * the first timer interrupt, so maybe we *do* have to thwack

        * the stupid ICU.

        *

        * Or maybe we have to reset the stupid "interrupt latch", but

        * that fucking GENIUS Todd Dutton, although he took the fucking

        * trouble to say that you have to reset the interrupt latch,

        * didn't take the fucking trouble to tell you WHAT THE FUCK

        * THE INTERRUPT LATCH IN QUESTION IS or HOW THE FUCK YOU RESET

        * IT, so if that's the problem, we'll have to wait for all the

        * 5000 FUCKING VICE PRESIDENTS AT DEC who have to sign off on

        * the FUCKING IDEA OF ACTUALLY LETTING SOMEBODY WHO WANTS TO

        * BUY LOTS OF YOUR FUCKING BOXES TO RUN THEIR SOFTWARE ON

        * actually GET THEIR HANDS ON ENOUGH FUCKING DOCUMENTATION

        * TO MAKE THEIR SOFTWARE WORK. GOD FUCKING FORBID that DEC

        * actually SELL any of these boxes, that might mean they might

        * CONTINUE TO MAKE MONEY, and we couldn't let THAT happen,

        * COULD we?

        *

        * No, I'm not bitter. Bitter is for wimps. I'm fucking

        * HOMICIDAL. I want the fucking HEADS of all the DEC people

        * who have stalled on this ON FUCKING POLES OUTSIDE MY OFFICE.

        * Interrupt handled by the master ICU;

        * send an EOI to it for this level, because

        * they *appear* not to set up the ICU for

        * a mode that preserves the fully-nested

        * structure.

        *

        * Of course, given how FUCKING HELPFUL they've

        * been about answering questions and providing

        * documentation, I had to find that out by

        * DECOMPILING THE FUCKING INTERRUPT HANDLER

        * CODE IN OSF/1.

        *

        * I hope they FUCKING GO BANKRUPT, lose their

        * FUCKING jobs and ALL their FUCKING undeserved

        * self-esteem, and end up OUT ON THE FUCKING

        * STREET.

        *

        * I hate them. I hate talking to them. I hate sending

        * them mail. I hate *receiving* their mail. I hate

        * *reading* their mail. I want them all to die SLOWLY

        * IN HORRIBLE PAIN.

        */

        /*

        * N.B.: As of 1999, they did, when Compaq and Intel

        * dismembered DEC like blood-maddened piranhas.

        * Requiescat in pace.

        */

  11. Unep Eurobats
    Paris Hilton

    So...

    Ceci n'est pas un comment.

    1. Warm Braw

      Re: So...

      Ceci est un "comment?"...

      1. Bloakey1

        Re: So...

        "Ceci est un "comment?".."

        Mais ici j'ai un comment allez vous?

  12. Forget It
    Linux

    Codes

    shoots

    and

    leaves.

  13. Herby

    Reflection on the author...

    Comments, while not used by the compiler, are written by the same person who writes the code. In general, one reflects upon the other. If you see "bad (sloppy) comments", there is (I suspect) a similar fate for the code in general.

    So, if you see bad code (and that is everywhere!), bad comments are not far behind. So, cleaning up comments to reflect the code in general is probably a "good idea".

    Just remember:

    Bad, or incorrect comments are worse than no comments at all. Documentation is something that needs to be done.

    1. sabroni Silver badge

      Re: Bad, or incorrect comments are worse than no comments at all

      But this wasn't a rant about the content of the comments, it was about the structure of the comments tags. If the comment is useful but the format is slightly different to the other comments what difference does it make?

      1. Pascal Monett Silver badge

        For someone who is obsessively anal, it does make a difference.

        For those who want absolute control over every single part of what they see and do, it must be quite irksome to have other people do things slightly differently.

        For my part, if you want to box your comments, it's your time to spend. As long as the comment itself is useful, I fail to see why that is important.

        I'm obviously not obsessively anal enough.

        1. Doctor Syntax Silver badge

          "For someone who is obsessively anal, it does make a difference."

          Which is a good trait in someone maintaining an OS kernel.

          1. Pascal Monett Silver badge

            When it comes to comment format, it's a tad exaggerated.

        2. Flocke Kroes Silver badge

          Boxing comments

          Yes very pretty, until a function has to handle some new possibility, and the boxed comment updated to match. Next you will start tolerating spaces left in front of tabs.

        3. PaulFrederick

          If someone needs to edit your comment then you're spending their time too.

    2. bombastic bob Silver badge

      Re: Reflection on the author...

      "Bad, or incorrect comments are worse than no comments at all. Documentation is something that needs to be done."

      With doxygen, you can kinda get BOTH at the same time (but you have to format the comments properly, and that goes back to Linus' rant)

    3. Naselus

      Re: Reflection on the author...

      "If you see "bad (sloppy) comments", there is (I suspect) a similar fate for the code in general."

      It's only sloppy if they mix and match, which there's no indication hat they have done. Linus is just being an asshat here tbh. I can't even tell the difference between a couple of his 'acceptables' and 'unacceptables'.

  14. Zakhar

    There is a reason to do

    /*

    blah blah

    blah blah

    */

    and not otherwise. If 'blah blah' happens to be a block of code you commented out, you want a fast method to uncomment: just remove 2 lines.

    For a single line commented out, // at the beginning might be better for that use.

    But certainly those are comments while you are still debugging your code, and not something you want in a 'production' release.

    Then in 'release' code, it boils down to readability and personal taste.

    ... and I do personally like nice "boxes"!

    1. GrumpenKraut
      Boffin

      > ... just remove 2 lines.

      Way too much work.

      #if 1

      ...code...

      #endif

      Now I need to change 1 to 0 to "comment out" that code. With an additional #else I use this to switch between different code versions, such as "slow but obvously correct" and "highly cryptic and powerful".

      1. Woza

        It sounds harmless but the trick is knowing when to stop - I've seen nested messes of

        #if 0

        #if 1

        #if 1

        #if 0

        ....

        that have to be seen to be believed. It makes grep happy too!

        Icon: The goggles, they do nothing!

    2. Flocke Kroes Silver badge

      @Zakhar

      /*

      blah("*/crash_and_burn()/*");

      */

    3. bombastic bob Silver badge

      "If 'blah blah' happens to be a block of code you commented out, you want a fast method to uncomment: just remove 2 lines."

      how about this:

      #if 0

      commented = out * code;

      fprintf(stderr, "line %d in %s\n", __LINE__, __FUNCTION__);

      #endif // 0

      works nice for test or debug code.

      Using the '#if 0' block makes it so that if your code contains /* */ comments, you can STILL 'comment it out' with only 2 lines, but then you only need to change the '0' to a '1' to re-enable it afterwards...

      or you could get really good at 'tapping out' the keystrokes for putting // at the beginning of a bunch of consecutive lines of code (being a drummer helps), using a rapidly repeated sequence of '//' left, left, down with left hand on '/', right hand on cursor keys [or else use a keystroke recorder to make a macro of it, playable with a hotkey]

      1. Charles 9

        But as Woza noted, what if they start nesting? Plus the commenting techniques works better in editors with syntax highlighting since commenting the code will make it look obvious it's non-functional.

  15. tin 2

    I am sorry, everyone here is wrong, including Linus. The correct format is.

    10 REM this is a comment.

    We forget so easily.

    1. Doctor Syntax Silver badge

      "10 REM this is a comment."

      Sorry, your newfangled BASIC stuff just doesn't work in Fortran and Assembler.

      1. qwertyuiop

        REM?

        Surely the way to indicate a comment is with an asterisk in column 8?

        1. Someone Else Silver badge

          Re: REM?

          Surely the way to indicate a comment is with an asterisk in column 8?

          No, no! It's a 'C' in column 6! Enny fule no dat!

      2. tin 2

        A comment in assembler? There ain't no memory for comments in assembler!

        1. Charles 9

          "A comment in assembler? There ain't no memory for comments in assembler!"

          I would think comments IMPROVE the assembly process, since it can IGNORE any line that (IIRC) begins with a semicolon.

          1. tin 2

            You're obviously assembling on something with a lot more memory than I :)

  16. herman

    Well, fortunately he isn't complaining about something important, but this kind of cruft is the reason d'etre of pretty printers.

  17. muddysteve

    Personally, I have always believed that comments are far more important than any other kind of documentation, on the basis that they are more likely to be kept up to date.

    1. Doctor Syntax Silver badge

      "that they are more likely to be kept up to date."

      Not necessarily, but at least they're where you want them.

  18. wolfetone Silver badge

    I think anyone who has worked on someone elses code has smashed a screen or two when they've found poorly written comments, poorly formatted comments, or absolutely no comments whatsoever. It's vital for a piece of software, especially one as large and complex as Linux, to have a standardised way of commenting and have those comments easily readable. Otherwise mistakes will happen.

  19. This post has been deleted by its author

  20. lset

    From my experience, and I can only speak based on that, the use and formatting of comments is really important. All documentation is important in all aspects of IT and should be take seriously.

    On the flip side, Linus once again acts as the directory definition of "its not what you say, but how you say it". I respect his work but there are ways of writing a stern email without resorting to that language -__-

  21. okand

    I wonder if Linus has ever actually tried LSD...

    1. Anonymous Coward
      Anonymous Coward

      "I wonder if Linus has ever actually tried LSD..."

      I wonder if he's ever tried Prozac...

  22. Gunboat Diplomat

    Astounded

    I'm always astounded at these childish outbursts. I've got a lot of respect for the kernel devs who put up with this man's shit. I wouldn't stay on a project if the lead behaved like that.

    1. Mario Becroft
      Flame

      Re: Astounded

      I wouldn't stay on a project if team members insisted on submitting inconsistently commented, sub-par code.

  23. sabroni Silver badge

    IDE?

    In Visual Studio I just select the lines I want commented and click the comment button. That gives me a consistent comment style (appropriate to the language being edited) with zero effort.

    Isn't there a similar feature for Linux devs?

    1. John Sturdy
      Boffin

      Re: IDE?

      Emacs does all that (including, for a more keystrokes, boxed comments, should your really want them).

      One keystroke does most of the commenting stuff: start a comment, realign an existing comment, comment out a block of code or uncomment it back in again.

      1. Mario Becroft
        Thumb Up

        Re: IDE?

        Precisely. It's not rocket science.

  24. John Robson Silver badge

    I used to have pretty squares around comments...

    But then I worked somewhere with a mandated editor and a metric crapload of macros baked in.

    You'd type virtually any keyword and about 15 lines of stuff would appear - the appropriate statement, formatted according to style, a comment box, custom logging options etc etc.

    It was actually really nice - because you could just write the code, and the house style just happened around you - and it made it really easy to fill in the logging details and comments.

    Never had to worry about aligning the stars though - the macros handled it for me.

    1. Anonymous Coward
      Anonymous Coward

      Re: I used to have pretty squares around comments...

      "Never had to worry about aligning the stars though - the elder gods handled it for me"

      Fixed that for you.

      Personally, I tend to write a lot of comments while figuring out the shape of the new code, but once the code's actually working, unless the logic is amazingly complicated or obscure (usually due to external factors), it'll all be deleted. I'm much more a fan these days of making the code itself as clear and self-documenting.

      Mind you, one thing that did keep me vaguely amused at a previous place of employment was finding occasional comment-gems buried in ye olde codebase which drove much of their systems. I even ended up recording a few for posterity...

      /**

      * This makes baby jesus cry.

      *

      * It *really* needs refactoring.

      */

      ////////////////////////////////////////////////

      // Joe Bloggs - 10th October 20XX

      // It's Tuesday - it's not stopped raining since yesterday :(

      ////////////////////////////////////////////////

      // Farewell, cruel world

      die;

      /*

      * Halp, I'm being held hostage inside a software factory where I'm made to write the following shite

      */

      // thank goodness you're here, bizarrely circumlocutory error handling mechanism!

      // Function : <xyz>

      // A.K.A : <abc>

      // Purpose : To stop me ever having to type this farty little bit of boiler plate code again :-)

      ... and so on!

      1. Doctor Syntax Silver badge

        Re: I used to have pretty squares around comments...

        "occasional comment-gems buried in ye olde codebase"

        I once used Microsoft (or maybe MicroSoft in those days) FORTRAN for CP/M which included assembler for some library stuff. In the middle of that was a note left by one dev for another to the effect of "I can't get this stuff to work, can you?".

      2. GrumpenKraut
        Happy

        Re: I used to have pretty squares around comments...

        In a piece of Perl code, from the top of my mind (and translated from KautSpeak):

        # Crap implementation of [something], wouldn't have to do it

        # if that lazy [Firstname] [Lastname] had done his bloody job:

        ... code ...

        With the actual name right there.

      3. John Robson Silver badge

        Re: I used to have pretty squares around comments...

        "Personally, I tend to write a lot of comments while figuring out the shape of the new code, but once the code's actually working, unless the logic is amazingly complicated or obscure (usually due to external factors), it'll all be deleted. I'm much more a fan these days of making the code itself as clear and self-documenting."

        Code should say what it does - Comments say why.

  25. nigkettle

    There may be a reason..

    ..But it's not a good one. Leaving code like that means that at a glance I can't tell that it's commented out, especially if it grows beyond 2 lines. And any good editor will either be able to un-comment it for you or let you define a macro to do it in no time.

    And in production code it does boil down to readability .. but readability for *everyone*, not just the author, and standardisation certainly helps with that.

  26. John Sturdy
    Coat

    C++ comment syntax?

    C++ didn't introduce the //. It reintroduced it; it came from BCPL, a predecessor of C.

    Mine's the mammoth-skin cloak.

    1. Geoffrey W

      Re: C++ comment syntax?

      Oh man, flashback. I wrote a disassembler in BCPL way too long ago, on a super brain. I gotta go lie down now.

  27. circusmole
    Happy

    Well...

    ...nano highlights comments, what more do you need :-)

    1. Geoffrey W

      Re: Well...

      I need something mellow after all these coding comments. Can Nano help?

      1. circusmole
        Meh

        Re: Well...

        Absolutely. It's very lightweight, and doesn't make you feel bloated. I always get a good night's sleep after a dose of nano and a bit of C coding.

        1. Geoffrey W
          Unhappy

          Re: Well...

          I must be doing it wrong. I tend to get anxiety symptoms after a few hours of C. Well, C++, anyway.

  28. Dave 126 Silver badge

    Apollo Guidance Computer

    On a slight tangent from this topic, the source code for the Apollo computer has been uploaded to Github.

    http://www.theverge.com/2016/7/9/12136204/apollo-11-code-github

    Comments include:

    # "IT WILL BE PROVED TO THY FACE THAT THOU HAST MEN ABOUT THEE THAT

    # USUALLY TALK OF A NOUN AND A VERB, AND SUCH ABOMINABLE WORDS AS NO

    # CHRISTIAN EAR CAN ENDURE TO HEAR."

    The Apollo display and keyboard used two digit verb and noun codes for user input.

  29. Anonymous Coward
    Anonymous Coward

    RSI ?

    Typing // means less typing fatigue than /* */ . The slash is directly accessible on US keyboards, the asterisk requires shift. That alone should decide the issue.

    1. Doogs

      Re: RSI ?

      Does the US number pad not have an asterisk right next to the slash?

    2. Mario Becroft
      WTF?

      Re: RSI ?

      Do you not have an editor that has a comment command?

    3. Lee D Silver badge

      Re: RSI ?

      Fine for a one line comment.

      Now think that you might not want your comment to be several thousand characters long on a single line and you have a lot of //'s to insert.

      Hence why I use // for single-line comments and /* */ to mark beginning and ends for multi-line, without all the extra-asterix-rubbish in between (which just generates work if you ever try to re-jig that paragraph manually in a dumb text editor).

      It seems that that would be an acceptable style, so I'm not the only one.

    4. bombastic bob Silver badge

      Re: RSI ?

      "Typing // means less typing fatigue than /* */ . The slash is directly accessible on US keyboards, the asterisk requires shift. That alone should decide the issue."

      that, and people wearing wrist-braces from carpal tunnel syndrome.

    5. Someone Else Silver badge

      Re: RSI ?

      Are you that lazy a git that you'd even consider such a thing?

  30. pakman
    Coat

    BSD got it right

    This is my type of comment:

    <code>

    .\" Take this out and a Unix Daemon will dog your steps from now until

    .\" the time_t's wrap around.

    .Pp

    You can tune a file system, but you cannot tune a fish.

    </code>

    Source at https://svnweb.freebsd.org/base/stable/11/sbin/tunefs/tunefs.8?revision=302408&view=markup#l211

    I wonder what Linus thinks about that one. Mine's the one with the tone-deaf tuna in the pocket....

  31. Alan Bourke

    What a

    dickhead crybaby he continually proves himself to be.

  32. Croc O'Dial

    What does he have against asterisks?

    He doesn't like asterisks, then? Let him try this comment for size.

    /* Linus, go **** yourself */

  33. Anonymous Coward
    Anonymous Coward

    Call me stupid but isn't it trivial to write a bash script that parses the code and converts the comments into the required format?

    This is Linux after all.

    /* I don't know what the fuss is all about */

    1. Flocke Kroes Silver badge

      Hi Stupid

      If it really is that easy then style challenged devs could use such a script before submitting code for the kernel. (I would go with indent rather than bash.)

    2. Malcolm Weir Silver badge

      OK, Stupid...

      No. No, it's not trivial. Consider how you'd handle:

      printf("*/ or \"/*");

      To do it right, you need a lexical analyzer. Of course it can be done, but doing it with bash would be a nightmare.

      1. Charles 9

        It wouldn't have to be THAT sophisticated. Syntax highlighters know the trick. You just have to be able to understand string demarcations as well as comment demarcations to realize you don't want to process those comment lines.

  34. Fruit and Nutcase Silver badge
    Paris Hilton

    Quotes

    The following query

    https://www.google.co.uk/#q=Linus+Torvalds+Quotes

    returns a sample of 3 quotes

    "Software is like sex: it's better when it's free."

    "Talk is cheap. Show me the code."

    "The Linux philosophy is 'Laugh in the face of danger'. Oops. Wrong One. 'Do it yourself'. Yes, that's it."

    Take the first and last...

    "Software is like sex: it's better when it's free. The Linux philosophy is 'Do it yourself'.

    1. Flocke Kroes Silver badge

      Re: Quotes

      Converse: Pay other people to do it while you watch.

  35. Gary Bickford

    He's being fairly tolerant on this apparently

    In my experience most groups have a defined acceptable style that is pretty strict, not a group of styles that are acceptable. In every case the group insists on using that style, period, no exceptions and code reviews include this aspect. For my part, having settled on using Doxygen for auto doc system, I've been using a tweaked set of Vim scripts that build the comment structures automatically so at least the form is there.

    In line documentation is a place where the 'principle of least surprise' applies. It is important for code readers to be able to scan quickly and absorb the essence without having to interpret unfamiliar comment layouts. This is similar to how drivers may have difficulty interpreting road signs when first driving in a new location that has different signage conventions. If variable declarations are _always_ precede by a comment description, even if it is empty, then the eye picks each variable up and now knows about it.

  36. Anonymous Coward
    Anonymous Coward

    I don't get it

    "He's also happy with this format:

    /*

    * This is also a comment, but it can now be cleanly

    * split over multiple lines

    */

    ...

    (no)

    /* This is disgusting drug-induced

    * crap, and should die

    */

    "

    Maybe it's just me, but I've utterly failed to spot any difference between the 2 comments, one being seemingly OK, and the other apparently a criminal offense in Linus' world.

    Creepy.

    1. GrumpenKraut

      Re: I don't get it

      And I thought I am a bad looker: in the second comment the embedded text start on the same line where the comment begins. 8^)

    2. MJI Silver badge

      Re: I don't get it

      Example 2 the first comment line is on the /* line

    3. Dan 55 Silver badge

      Re: I don't get it

      Slightly easier to move the comment text around inside the comment or between comments in the first one. Whether or not that merits that outburst is something else.

    4. WuzYoungOnceToo

      Re: I don't get it

      <<stoplikingwhatidontlike.gif>>

    5. oldcoder

      Re: I don't get it

      That is only because the article didn't put them in preformatted blocks. They actually are different.

  37. digiman
    Happy

    All I can say is . . .

    /* NO COMMENT */

  38. Anonymous Coward
    Anonymous Coward

    Like Zero Tolerance policing...

    Keep a disciplined eye on what seems trivial and you'll often find the non-trivial stuff gets disciplined too.

    1. Dan 55 Silver badge
      Trollface

      Re: Like Zero Tolerance policing...

      The broken Windows theory?

      1. Anonymous Coward
        Anonymous Coward

        Re: Like Zero Tolerance policing...

        That's superb! Please accept an upvote.

  39. Al fazed
    Happy

    Anal ? Obsessive ?

    IMHO it is unfair to ridicule someone for their disability.

    If someone is obsessive, then there is probably a good reason for their behaviour.

    If you want to work with someone who is this way, then you have to make allowances for their disability.

    If you cannot, then you should be working somewhere else, as you will not enjoy the ride and you will spoil their fun by moaning all the fucking time.

    People who are obsessive may be medically classed as OCDC, Autistic, Asperges, et al.

    The irony is, that people who are obsessive often make the best coders, quality controllers, testers, validators, analysists, musicians, artists, writers, poets, architects, engineers, inventors.

    Critics criticise, they rarely produce anything of value by them selves.

    Apart from unrest and dis-ease.

    A little appreciation of the mentally challenged amongst us would be in order.

    Must be on the wong drugs !

    ALF

    1. Anonymous Coward
      Anonymous Coward

      Re: Anal ? Obsessive ?

      You make an excellent point about some of the positives of being on the autism spectrum, and equally well, I appreciate how difficult it can be to attempt to adapt to working with other people who perhaps don’t have quite such an attention to small details. That’s an absolutely invaluable skill to have, but at the same time there has to be at least a small amount of trying to be less abrasive in terms of interpersonal communications and relationships, otherwise it really does make for an absolutely horrible working environment for everyone else (who, bear in mind, may also have very useful skills in other areas).

      Yes, I have had extremely bad experiences with this, to the extent of having affected my mental wellbeing extremely badly.

      1. Charles 9

        Re: Anal ? Obsessive ?

        Especially if you end up with a situation of TWO obsessives at odds with each other. Since neither one will normally back down, you're in for a rough time.

  40. cloned67

    What You See Is What You Like (** just use an auto-format tool )

    IMHO

    it would be far better, for people that have problem with other people style,

    and given the enormous almost useless overpower of today's text editors

    to just write an auto format plugin for their favorite editor

    in order to convert (on the fly),what to them looks annoying in something pleasant to see

    keeping the stored either intact or with a conventional floor shape

    instead to force everybody stick with some common floor level

    having so almost everybody unhappy at reading it

    let's start the WYSIWYL Epoch!!

    :D

  41. Anonymous Coward
    Windows

    Just saying...

    He should worry about the crappy shareware code, not the comments!

  42. Anonymous Coward
    Anonymous Coward

    Commentards

    Commenting on commenting in code.

    Bizarre.

    If a customer asks me to comment my code I copy/paste from this here website.

    Its the best source on the internet for comment snippets after lorem ipsum.

  43. Anonymous Coward
    Anonymous Coward

    Time for Linus to go?

    Whilst it is amusing to read about his petulant rants, I can't see this helping his project at all.

    If he is so competent, is is really beyond him define some standards and run the code through a formatter like, oh I dunno, what happens at every professional outfit on the planet? Actually, seeing as how he kind make his mind up what comment style he want - I guess it must be.

  44. Mario Becroft
    Thumb Up

    I agree with Linus

    If you take a moment to look, the styles he is complaining about *are* plain crappy. If you must use asterisks throughout your comment, at least align them. That's kind of the whole point.

    May sound petty, but to professionals, basic code tidyness and consistency should go without saying. If my team was submitting sub-par code like this and expecting me to deal with it all the time I would soon be on a short wick too.

  45. lukewarmdog
    Devil

    Job Security through comments

    / this is to keep the website compatible with IE8

    /required for "Java VM 1.05b (overnight beta build)"

    /this will resolve itself in the future. If you are reading this in the future, delete this code block

    Now we play the waiting game. Whoever replaces me will 100% remove my code snippets and everything will stop working. A plan so cunning Dan Brown is probably writing a book around it now.

  46. Anonymous Coward
    Anonymous Coward

    { pfft }

    You know what grinds my gears?

    - all those curly brackets getting lines to themselves in 'C' ,and sequels.

    Messy!

    looks hideous!

  47. mike acker

    /* -----------------------------------------------------

    everybody knows

    comments are supposed to be in

    little boxes

    ------------------------------------------------------ */

  48. Tom 7

    Its 2016 isnt it?

    Old habits die hard but even most terminal text editors have syntax highlighting these days*. I'd be a bit worried if someone was using nano to develop kernel code until I knew they could handle it.

    * I was doing some ARM assembler on a pi zero the other day and even that had colour 'syntax' highlighting!

  49. heyrick Silver badge

    All of Linus's examples are wrong

    If he wants balanced and pleasing, the asterisks from the second line down should be indented one space to line up with the top asterisk. Anything else is fugly.

    FWIW, I use C++ style most of the time.

    1. fnj

      Re: All of Linus's examples are wrong

      @heyrick

      If he wants balanced and pleasing, the asterisks from the second line down should be indented one space to line up with the top asterisk. Anything else is fugly.

      Damn right. But I don't think we can tell from TFS whether he intends to show them lined up or not. I was trying to figure it out from the context, and gave up. Using proportional fonts when showing code is unclear and lazy.

  50. Sil

    Micromanagement at its best, or how to demotivate workers on issues with no importance whatsoever.

  51. AndrewDu

    I'm offended.

    I remember spending hours getting the asterisks to line up when writing Fortran IV back in the 60's.

    Who do I call?

  52. sisk

    I really don't understand why the networking people think that their particularly ugly styles are fine.

    Um....Perhaps because they ARE fine.

    Seriously, Linus has lost his mind with this one. Who cares what commenting style they use? As long as you can tell a comment from a code (and if you can't then you really shouldn't be working on the kernel) it makes no difference.

  53. IsJustabloke
    Facepalm

    hmmmm...

    He's a bit of a "ladygarden" really isn't he?

  54. DrXym

    Code consistency is important

    Anyone who has been on a large project knows everyone has their own ideas about indentation, use of spaces / tabs, formatting, braces on end of lines, naming conventions, ordering of #includes, public / private code etc.

    You have to have a common coding style or the free-for-all becomes a dog's dinner with a greater chance of bugs being introduced. In addition patches can become a real mess if someone reformats a style or mixes their own style in with the rest of the other code.

    I'm hardly surprised that the Linux kernel should enforce a coding style. It already has a document for this but oddly the network drivers are excepted from using the normal comment convention. Clearly Linus has gotten so pissed off with this exemption that he's put his foot down. I don't suppose it would be hard to write a perl script that fixed this in a single patch. Probably that will happen if it hasn't already.

  55. Anonymous Coward
    Anonymous Coward

    Silly boy

    /* Linus Torvalds

    * is a silly boy

    */

  56. Bucky 2

    Change over time

    The argument in favor of Linus's preferred commenting format is that when the code changes, then the comments sometimes must be changed, too.

    Comments with asterisks on the right are unnecessarily cumbersome to modify.

    Taking a step back, we could conclude that developers that DO use asterisks on the right are not concerned about modifying code over time.

    Taking another step back, we might conclude that developers who are not concerned about modifying code over time are foolish, or arrogant.

    Taking another step back, we might decide that developers who work on kernel code could not be foolish, and therefore such comments are a display of arrogance.

    You can't deal with arrogant people politely. You have to tear them a new one, or they won't listen.

    It's a lot of presumptions. And any one of the steps could be false if you took some time to evaluate them. But you don't actually take the steps individually. You flash from the beginning to the end in blind fury.

    1. Charles 9

      Re: Change over time

      "You can't deal with arrogant people politely. You have to tear them a new one, or they won't listen."

      But you can't be TOO rude to them, either, or you make them retort, "Yeah, well $#$ YOU!" and then double down, making them even less receptive to change.

  57. J.G.Harston Silver badge

    How do I get <tt> to work?

    While in general I tend to comment as per Linux, I do right-justify stars if they are comments on the end of a line. See past the formatting, something like this:

    switch(n) {

    ....case 1: one(); */.one...*/

    ....case 2: one(); */.two...*/

    ....case 3: one(); */.three.*/

    ....case 4: one(); */.four..*/

    ....}

    1. Charles 9

      Re: How do I get <tt> to work?

      The counter is that you SHOULD be doing double-slash comments if they're inline like that. No right asterisk necessary anymore there.

    2. DrXym

      Re: How do I get <tt> to work?

      I can spot about 8 things wrong with that snippet.

      But on a general point, end of line comments are usually never a good idea. There are exceptions of course, but it's usually clearer to put a comment before a piece of code rather than after it. Especially if the code has a formatter like astyle run over it.

  58. SeanEllis
    Holmes

    Linus hates sloane squares

    The great Verity Stob, late of this parish, anticipated the problems of comment layout in her own appendix to The Meaning of Liff.

    In it, she defined the sloane square (n.) A program comment contained entirely in a box of ******s. A leicester square, incidentally, is a bastard sloane square where all the verticals are out of alignment as a result, for example, of the printer having the wrong tab value.

    Linus, it appears, really hates both varieties of square.

  59. John70

    /*****************************************************************

    * So does Linus like this comment since he didn't list it?

    ****************************************************************/

    1. Charles 9

      That's the style I use. I don't know how Linus would personally feel about it, but based on the examples, I don't think he'd be too annoyed with it. I think what ticked him off was poor formatting and poor consideration for editing in future. That style doesn't seem to trip those landmines.

  60. tekHedd

    I agree

    If you can't make a simple comment readable and consistent with community standards, I would not expect you to be able to design code for maintainability either.

    Every time Linus goes on another rant, I like him more.

  61. nautica Silver badge
    Happy

    Poor Linus...

    One particularly well-informed, intelligent, and THINKING expert has posited that the recent rash of Linux-OS sh*t, as best exemplified by the abortion known as Ubuntu 16.04, is likely heralding the end of any hopes of--and indeed, even the death of--Linux on the desktop. This comedy by Linus Torvalds does nothing to make one feel good about being at odds with this prognostication.

    "Programming is the art of telling another human being what one wants the computer to do."--Donald Knuth

    "Programs are meant to be read by humans and only incidentally for computers to execute."--Donald Knuth

    "Besides a mathematical inclination, an exceptionally good mastery of one's native tongue is the most vital asset of a competent programmer."--Edsger Djikstra

    1. foo_bar_baz
      Devil

      Re: Poor Linus...

      The Linux kernel is open source. There's nothing Linus can do about people making crappy distributions based on the kernel.

      1. Charles 9

        Re: Poor Linus...

        That's not the issue. He's ticked about crappy edits TO the kernel, and he DOES have moderation power in this case.

        Making crappy distros based on the kernel is outside the scope and a different matter altogether.

  62. This post has been deleted by its author

  63. Anonymous Coward
    Anonymous Coward

    VMS was a great kernel

    And I recall there were comments of the form "don't even try to understand this code." http://www.perlmonks.org/?node_id=156816

    Such comments also seen in a buffer overflow attack I found on my PC running linux circa 1999. Apparently from some Romanian guy.

  64. Anonymous Coward
    Anonymous Coward

    But if I commented my code...

    ...they might sack me.

    And if they sacked me...

    ...the system would stop.

    ...you are not expected to understand this.

  65. Herby

    Maybe one should try...

    To look at the code using an ASR33 teletype. Unfortunately it has no lower case, but just setup a terminal connection at any 3 digit speed and edit the code. Lots of "fluff" in comments is annoying, but at the slower speeds, just about anything that isn't code comes close (unfortunately).

    The best test of how well you commented code is to go away for about 6 months (maybe longer) and come back to the code and resume with the project. You WILL understand the need for legible comments.

    Fancy boxey comments are just annoying, but that's my opinion.

  66. iOS6 user

    indent?

    Is it really so hard to use source code formatting tools or use existing one?

    What is the problem with passing all kernel code over such filters and do one final commit to git before final release?

    $ man indent | grep -- -comment

    -bbb, --blank-lines-before-block-comments

    -cn, --comment-indentationn

    -cdn, --declaration-comment-columnn

    -cdb, --comment-delimiters-on-blank-lines

    -dn, --line-comments-indentationn

    -fc1, --format-first-column-comments

    -fca, --format-all-comments

    Set maximum line length for non-comment lines to n.

    -lcn, --comment-line-lengthn

    -ncdb, --no-comment-delimiters-on-blank-lines

    -nfc1, --dont-format-first-column-comments

    -nfca, --dont-format-comments

    -nsc, --dont-star-comments

    -sc, --start-left-side-of-comments

    --blank-lines-before-block-comments -bbb

    --comment-delimiters-on-blank-lines -cdb

    --comment-indentation -cn

    --declaration-comment-column -cdn

    --dont-format-comments -nfca

    --dont-format-first-column-comments -nfc1

    --dont-star-comments -nsc

    --format-all-comments -fca

    --format-first-column-comments -fc1

    --line-comments-indentation -dn

    --no-blank-lines-before-block-comments -nbbb

    --no-comment-delimiters-on-blank-lines -ncdb

    --start-left-side-of-comments -sc

  67. Tom 38

    Style is important

    Particularly since Linus's job is not really writing code, but merely reviewing and merging code. Consistency of style makes code easier to read and comprehend.

    Perhaps Linus needs to write a style(9) guide man page, and refuse to merge anything that does not match.

    It is probably harder for Linux, being a disparate project. For things in FreeBSD kernel and world (non contrib parts, anyway), nothing gets committed that breaches style(9), and if it does, anyone with a commit bit can change it so that it doesn't.

  68. Joe Gurman

    It's not amusing

    ....when an abusive person suffering from OCD verbally abuses other people with OCD. Or not enough OCD for his tastes.

  69. John Savard

    Good Grief!

    This kind of stuff makes me think it's time to fork the Linux kernel, and leave Mr. Torvalds be until he finds the help he needs and gets better.

    Comments are important, and comment styles can vary in readability, but I find the distinctions he is making here incomprehensible.

  70. ShrNfr

    /*********************************/

    /* This is what we used */

    /* in PL/I */

    /********************************/

    /* tough if you don't like it */

  71. WuzYoungOnceToo

    I love the part about "have nothing better to do than to worry about the right alignment of the asterisks" when he's bitching about the difference between....

    /*

    * This is also a comment, but it can now be cleanly

    * split over multiple lines

    */

    ...and...

    /* This is disgusting drug-induced

    * crap, and should die

    */

  72. oldcoder

    It would actually help if the comment examples were placed inside a pre /pre brackets (along with code /code) to show the examples CORRECTLY.

  73. smartypants

    The art of comments never taught properly

    Comprehensibility should be one of the foundations of software engineering but I've lost count of the otherwise brilliant engineers who have crossed my paths who either can't or won't comment their code properly.

    It's a bit like testing in that regard. Some see it as something to do later if at all, yet there can be few of us that haven't suffered the consequences.

    It is odd. I wonder if other engineering careers are similarly dysfunctional!

  74. Anonymous Coward
    Anonymous Coward

    The comments could actually be "cleaned up" automatically when the code is pulled from all over. He wrote git from scratch, but he can't write a simple code (comment only) formatter to go with it. Shiiiiiiiiiiiiiiiiiet!

  75. Anonymous Coward
    Anonymous Coward

    Why not C style the Kernel?

    I am a bit surprised this discussion even had to be started.

    Solaris has been C style clean for decades and hooks are used to prevent any push into the tree that does not pass the C style checker.

    Presumably the kernel could be C style cleaned up and new integrations automatically blocked unless the changes were also C style clean.

    I am somewhat surprised that the Linux Kernel people haven't been doing this all along.

  76. Anonymous Coward
    Anonymous Coward

    Sweary Toung in cheek response, let the flame wars commence!

    See you need to copy and paste this into a fixed width editor for this to make any sense

    xterm works well!

    /*

    ***********************************************************

    * THIS IS PROPER OLD SCHOOL UNIX/C MY *

    * YOUNG APPRENTICE *

    * *

    * Yes I agree that a lot of people who comment in this *

    * style may like the occaisional tipple into the strange *

    * and magical world of LSD! They also write comments *

    * like this from tunefs(8) in SunOs 4.1.1 when the x86 *

    * was just born and Microsoft were not so big and this *

    * quirky little thing called the Linux Kernel was just *

    * being developed and folk like me were patching flawed *

    * device drivers just to get their system to boot with *

    * dirty #defines to get around the changing PCI id's of *

    * cards that were just coming out on an all new bus *

    * *

    * Again before your time linus but cards coming out on a *

    * bus is a bit like the electronic version of the *

    * Village people doing a performance entirely based on *

    * public transport! *

    * *

    * A lot of our code was shite because we wern't interested*

    * in an elegant solution, that's what you guys were for *

    * "I've got it working now go and be a good boy and tidy *

    * this up for me, here is the problem, I'm off to solve *

    * the next obsure bug in my hardware" *

    * *

    * Our code was tempory but our comments should last *

    * forever because:- *

    * 1. We're funnier *

    * 2. We're fluffier *

    * 3. We have supirior patience with the space bar and *

    * can instinctively plan way way way ahead of you; *

    * 4. We know how much you want to edit the crap out of *

    * this shit but hey! I just right justified the 2^ *

    * lines above just because I can and if this were; *

    * "Linus Christ Forgive" a real .c file containing *

    * 'real' code then every forth or fifth word would *

    * bee some kind of ridiculous pun or obscure fact. *

    * *

    *=========================================================*

    *** The definition of a "line us tor valds" is simply ***

    *** WE DREW THE LINES BEFORE...... Valds Debt existed ***

    *** ***

    ***-----------------------------------------------------***

    ***** Here lies the last remnants of a distant realm. *****

    * *

    * Beware of Dragons masquarading as IP Packets! *

    * *

    * Nufsed! *

    **********************************************************/

    // insert C++ code here, fuck it use ruby, or any other bulshit you like, I don't care, cause I can optomize assember to use opcodes as

    // friggin constants to save on ROM space! (systemd is both bulshit and quite good, they probably use comments like this, you pays

    // your money, you takes your choice!

  77. Anonymous Coward
    Anonymous Coward

    I have a perfect comeback for this!

    It would hopefully start the flame war to end all flame wars, hence why the content filter wouldn't let it past.

    Probably for the best since it only made real sense when opened in vi or emacs.

    In the land of my hidden FaceBook it will reside then!

    Never Mind!

    Maybee I'll put it on SourceForge for someone to make compile!

  78. Leon9

    For going nuts on such petty issues, maybe Linus is "out of [his] mind on LSD"

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

Other stories you might like