Linus must be running out of things to do!
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 …
COMMENTS
-
-
-
-
This post has been deleted by its author
-
Monday 11th July 2016 22:31 GMT 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.
-
-
Monday 11th July 2016 20:15 GMT 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.
-
-
-
-
Monday 11th July 2016 08:44 GMT 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.
-
-
-
This post has been deleted by its author
-
-
-
Tuesday 12th July 2016 11:50 GMT 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...
-
Wednesday 18th January 2017 08:45 GMT 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).
-
-
-
-
-
-
Monday 11th July 2016 06:56 GMT 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.
-
-
Monday 11th July 2016 07:04 GMT 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.
-
-
-
Monday 11th July 2016 08:51 GMT AndrueC
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.
-
Monday 11th July 2016 09:41 GMT GrumpenKraut
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.
-
Monday 11th July 2016 13:59 GMT AndrueC
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!
-
Monday 11th July 2016 14:05 GMT AndrueC
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.
-
Monday 11th July 2016 14:47 GMT GrumpenKraut
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.
-
-
-
Monday 11th July 2016 10:47 GMT 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.
-
Monday 11th July 2016 19:29 GMT Malcolm Weir
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.
-
-
Monday 11th July 2016 10:54 GMT 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.
-
Monday 11th July 2016 11:06 GMT 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.)
-
Monday 11th July 2016 15:16 GMT Someone Else
@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.
-
-
Monday 11th July 2016 22:42 GMT Roland6
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.
-
-
Monday 11th July 2016 11:23 GMT 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"
-
Monday 11th July 2016 15:19 GMT 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.
-
-
Monday 11th July 2016 11:38 GMT 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.
-
Monday 11th July 2016 11:40 GMT Hans Neeson-Bumpsadese
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
-
-
-
-
Monday 11th July 2016 11:37 GMT 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.
-
Tuesday 12th July 2016 00:27 GMT 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! */
-
Tuesday 12th July 2016 08:41 GMT nijam
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".
-
-
Monday 11th July 2016 14:42 GMT bombastic bob
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)
-
-
Monday 11th July 2016 07:06 GMT 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."
-
Monday 11th July 2016 07:33 GMT 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.
-
Monday 11th July 2016 09:37 GMT Doctor Syntax
"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.)
-
-
Monday 11th July 2016 14:59 GMT bombastic bob
"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')
-
Tuesday 12th July 2016 05:18 GMT 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.
-
Wednesday 13th July 2016 11:28 GMT 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.
-
-
-
Monday 11th July 2016 10:35 GMT 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.
-
Monday 11th July 2016 15:09 GMT bombastic bob
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].
-
-
-
Tuesday 12th July 2016 12:15 GMT 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..
-
Monday 11th July 2016 07:40 GMT 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".
-
-
Monday 11th July 2016 11:45 GMT 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.
*/
-
-
-
Monday 11th July 2016 08:04 GMT 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.
-
-
Monday 11th July 2016 08:50 GMT Pascal Monett
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.
-
-
Monday 11th July 2016 15:25 GMT 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'.
-
-
Monday 11th July 2016 08:07 GMT 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"!
-
Monday 11th July 2016 15:27 GMT bombastic bob
"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]
-
Monday 11th July 2016 08:28 GMT wolfetone
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.
-
This post has been deleted by its author
-
Monday 11th July 2016 08:40 GMT 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 -__-
-
Monday 11th July 2016 08:56 GMT John Robson
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.
-
Monday 11th July 2016 09:31 GMT 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!
-
Monday 11th July 2016 09:53 GMT Doctor Syntax
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?".
-
Monday 11th July 2016 09:55 GMT GrumpenKraut
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.
-
Friday 15th July 2016 14:59 GMT John Robson
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.
-
-
-
Monday 11th July 2016 08:59 GMT 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.
-
Monday 11th July 2016 09:55 GMT Dave 126
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.
-
-
Monday 11th July 2016 14:20 GMT Lee D
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.
-
Monday 11th July 2016 10:12 GMT pakman
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....
-
Monday 11th July 2016 10:58 GMT Fruit and Nutcase
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'.
-
Monday 11th July 2016 11:01 GMT 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.
-
Monday 11th July 2016 11:03 GMT 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.
-
Monday 11th July 2016 11:14 GMT Al fazed
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
-
Thursday 18th January 2018 18:10 GMT 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.
-
-
Monday 11th July 2016 11:19 GMT 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
-
Monday 11th July 2016 11:28 GMT 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.
-
Monday 11th July 2016 11:33 GMT Mario Becroft
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.
-
Monday 11th July 2016 11:44 GMT lukewarmdog
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.
-
Monday 11th July 2016 11:52 GMT 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!
-
-
Monday 11th July 2016 14:33 GMT 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.
-
-
Monday 11th July 2016 13:49 GMT 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.
-
Monday 11th July 2016 14:22 GMT 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.
-
Monday 11th July 2016 14:53 GMT 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.
-
Monday 11th July 2016 14:56 GMT J.G.Harston
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..*/
....}
-
Thursday 14th July 2016 08:10 GMT 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.
-
Monday 11th July 2016 15:07 GMT SeanEllis
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.
-
-
Tuesday 12th July 2016 19:50 GMT 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.
-
-
Monday 11th July 2016 17:35 GMT nautica
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
-
This post has been deleted by its author
-
Monday 11th July 2016 22:19 GMT 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.
-
Tuesday 12th July 2016 10:32 GMT 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
-
Tuesday 12th July 2016 12:28 GMT 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.
-
Tuesday 12th July 2016 21:18 GMT 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
*/
-
Wednesday 13th July 2016 05:53 GMT 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!
-
Wednesday 13th July 2016 13:55 GMT 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.
-
Friday 15th July 2016 01:50 GMT 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!
-
Friday 15th July 2016 06:15 GMT 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!