On the Linux Kernel Mailing List, Linus Torvalds has released another rant.
El Reg reports:
"Can we please get rid of the brain-damaged stupid networking comment syntax style, PLEASE?" the Linux Lord asked [July 8].
The Benevolent Dictator For Life gives 4 examples which he considers within norms and 2 more that are guaranteed to raise his wrath.
"I'm sure that looks really nice if you are out of your mind on LSD, and have nothing better to do than to worry about the right alignment of the asterisks."
Torvalds wonders if this kind of comment punctuation mess means it's time "... to start moving the whole kernel over to the C++ style, it's been many many years since we had compatibility issues and we are all used to it by now, even if we weren't all fans originally."
For now, he writes "I really don't understand why the networking people think that their particularly ugly styles are fine. They are the most visually unbalanced version of _all_ the common comment styles, and have no actual advantages."
(Score: 5, Funny) by dyingtolive on Tuesday July 12 2016, @03:09PM
TMZ, nerd style! SEE WHAT SHOCKING THING LINUS SAID NEXT AFTER THIS COMMERCIAL BREAK! Gasp!
Don't blame me, I voted for moose wang!
(Score: 2) by Runaway1956 on Tuesday July 12 2016, @04:20PM
I'm often amused by Torvald's rants. I am far more amused at the responses to those rants. People whine and snivel, "Oh, boo hoo hoooooo, Linus is being mean again!"
Punctuation? I could make a case that Linus makes to big a deal over it, but, fact is, I kinda agree with him. Ugly is ugly.
Abortion is the number one killed of children in the United States.
(Score: 0) by Anonymous Coward on Tuesday July 12 2016, @05:38PM
It isn't even really punctuation but comment tags. Title sounds like he's being a grammar Nazi, but I think the distinction is important.
(Score: 2) by HiThere on Tuesday July 12 2016, @07:40PM
IIUC, it's not being a grammar nazi, but rather an aesthetic critic. OTOH, the summary didn't give any examples.
Javascript is what you use to allow unknown third parties to run software you have no idea about on your computer.
(Score: 0) by Anonymous Coward on Tuesday July 12 2016, @03:14PM
When senior people start arguing over stuff like office decor as if they're matters of utmost importance, that suggests that someone's taking their eyes off the ball.
(Score: 3, Insightful) by jdavidb on Tuesday July 12 2016, @03:28PM
ⓋⒶ☮✝🕊 Secession is the right of all sentient beings
(Score: 0) by Anonymous Coward on Tuesday July 12 2016, @04:01PM
Its called making mountains out of molehills.
Most of them probably have macros to do it automatically.
(Score: 1, Informative) by Anonymous Coward on Tuesday July 12 2016, @05:33PM
I have dealt with this sort of thing in the past.
Usually one asshat decides *his* style is *the end all be all* of styles. Then starts smashing it all over the code (consult anyone? hell no! it doesnt *feel* right). Becoming basically a style cop. Then people commit something and that dude goes all ape shit because its 'not in the right format'. So the person spends the next hour reading up on *that* style and putting it in 'right'. The style cop is usually not happy at this point. They will find something else to nit pick about. In an open source project that is poison. As any sane person is going to be 'fuck that noise' and go work on something else. On a big enough project the rest of the group usually let them have 'their area' and they run it like a tyrant. But then they will find that power is not enough. The rest of the group is ignoring them and they will start to move their style into the rest of the code *and* be pissy on top of it. This KITH skit reminds me of what it is like sometimes https://www.youtube.com/watch?v=Z17rrnRRHDM [youtube.com]
My guess is this is what happened and Linus reminded everyone who has final say and what his preference is. Probably about the way I would have handled it. Basically 'put it back the way it was OH and fix your own shit to match the *rest* of the code'.
(Score: 3, Insightful) by Ethanol-fueled on Tuesday July 12 2016, @07:46PM
An ounce of prevention is worth a pound of cure. Anybody who goes into that project dam-well knows that they are getting into, and it's in their best interests to conform to the style, even if those comments will not be compiled into code.
I know, slippery-slope, yadda yadda -- but policing comment style is just yet another way to keep project workers from degenerating into doing whatever the fuck else they want and how they want it, which would threaten project cohesion.
I'd never willingly work under Linus, but I agree 100% with his management style. He's passionate about his baby and wants to maintain consistency.
(Score: 2) by driverless on Wednesday July 13 2016, @05:47AM
I think Torvalds is arguing that these guys have taken their eyes off the ball.
But obviously not off the asterisks.
(Score: 4, Insightful) by JNCF on Tuesday July 12 2016, @04:00PM
When senior people start arguing over stuff like office decor as if they're matters of utmost importance, that suggests that someone's taking their eyes off the ball.
I don't agree with everything in the rant, but do see value in consistent comment styling and I mostly agree with the styles he sees as adding more clarity without making comments tedious to edit (at least I assume these are his reasons, he doesn't make his actual objections to specific styles very clear). Is code readability really comparable to office decor?
(Score: 1, Informative) by Anonymous Coward on Tuesday July 12 2016, @07:34PM
What makes you think Linus considers this to be of utmost importance? He merely sent an email and even says it isn't urgent: "So just get rid of the (no-no) and (no-no-no) forms. Not in one big go, but as people touch the code, just fix that mess up."
This shouldn't even be a story. Unless you're a kernel dev you don't need to read everything Linus says on the mailing list, and this isn't even funny, interesting or a major insight.
(Score: 2) by JoeMerchant on Tuesday July 12 2016, @08:21PM
What ball? Where's the quarterly statement? If the users don't like the leadership, they're free to replace them at any time, no board meeting required.
Україна досі не є частиною Росії Слава Україні🌻 https://news.stanford.edu/2023/02/17/will-russia-ukraine-war-end
(Score: 4, Interesting) by Snotnose on Tuesday July 12 2016, @03:26PM
Our coding standard said all functions and data structures had to have that box of stars around it. Real joy trying to keep the right edge lined up right. Hate to think of how many hours were wasted on that crap, or how many times comments didn't get updated because someone didn't want to deal with lining things up again.
Then again, I was a consultant being paid by the hour....
I came. I saw. I forgot why I came.
(Score: 4, Informative) by Grishnakh on Tuesday July 12 2016, @04:11PM
Why would it be hard to keep the right side lined up?
All you have to do in vim is create a bunch of lines with the /* and */ on both sides ("yy20p" will make 20 lines once you have 1 like that), then start typing in with "R" (which overwrites the spaces between the stars, leaving them in place).
If that doesn't work in your text editor, then maybe you should use a real one instead of a crappy toy.
(Score: 4, Informative) by Anonymous Coward on Tuesday July 12 2016, @04:27PM
Creating them is easy, and nobody denies it. The objection is that editing them is a royal stinking pain, because you likely have to reflow to the end of the paragraph.
(Score: 3, Interesting) by krishnoid on Tuesday July 12 2016, @11:42PM
I've wondered about this -- are there vi/emacs modes or scripts that configure wrap to start at a column and end at another, so you can reflow text within a column? It seems like it would significantly mitigate this problem.
(Score: 3, Informative) by RamiK on Tuesday July 12 2016, @06:58PM
Insert key in most GUIs does the same as Vi's replace mode. Goes back at least to Windows's Notepad; Possibly DOS's Edit.
XFCE's Mousepad and Geany work the same too. Even Gimp's text insert works with Insert.
Firefox doesn't work with Insert. Neither Nano or Inkscape.
And now you know what I have installed on this machine for the most part.
compiling...
(Score: 2) by Grishnakh on Tuesday July 12 2016, @08:17PM
Yep, that's a good point about the insert key; I wasn't thinking about that because I almost never use it anymore and only use vim for writing code. But if nano has no way of doing that, that's a good reason not to use nano, at least for anything serious. (It's perfectly adequate for an ultra-small editor for extremely low-resource systems, ones where you won't be doing any coding but you might need to edit a configuration file.)
(Score: 2) by RamiK on Wednesday July 13 2016, @10:07AM
Nano is a safe default since all its shortcuts are visually listed in the interface at all times. It's crucial to have search-and-replace available over SSH or in the console to edit configuration files without having to learn regular expressions, Vi or emacs.
Ideally, there should two default editors that visually list all their commands: One with emacs-like shortcuts and one with Vi-shortcuts. They should only implement open, save, search, search-and-replace and syntax highlighting and nothing else. That would satisfy 99% of the sysadmin needs and will allow programmers that spend all their days in Vim and emacs to get by in the console and over ssh.
But in the great linux tradition, nano is good enough so no one bothers.
compiling...
(Score: 1, Funny) by Anonymous Coward on Tuesday July 12 2016, @08:32PM
Me Grishnakh! Me big e-peen!
(Score: 3, Interesting) by VLM on Tuesday July 12 2016, @04:52PM
emacs package rebox2
https://github.com/lewang/rebox2 [github.com]
Its in ELPA so you don't need to use github, just the usual use-package or whatever you use.
Could have needed it a long time ago, then again rebox2 is like six years old and I'm sure the dear departed rebox1 didn't suck too bad.
For any annoying task, there's a near 100% chance someone has an emacs package to automate it. Unfortunately theres only a maybe 98% chance that it works correctly. Its a fun game to play to try to imagine something or define something and then try to find the emacs package (or worse ... packages) for it.
Gotta be careful, I'm not a man driven easily to drink but some years ago I accidentally on purpose installed two automagical parenthesis managers and they actually fought each other and provided me code something like (ADD 2 2)). Yes they automatically UNbalanced the parens. I felt like I needed a whole bottle of whiskey by the time I debugged and repaired that situation. I think its one of those mental self preservation things where I can no longer remember the details, too traumatic. It was like the factory that makes the sausage factories went crazy, it was a horror movie.
(Score: 2) by frojack on Tuesday July 12 2016, @05:21PM
Your point is spot on, and explains why some linux community segments use a different style.
You take over code maintenance, and you tend to use the same tools and same macros as the prior maintainers, because doing anything else is disrespectful, seldom warranted, and any changes to comments still requires the "thousand sets of eyes" to re-check every single line.
So the new contributors fall in line, and do as their portion of the community has always done.
Linus is asking a lot of people to re-review and resubmit a lot of code for a mere personal prefference issue.
Point is every shop I've worked in had editor macros, and code reformatter utilities upon my arrival. I used them.
Its built into the tool-set. Nobody is painstakingly hand typing those boxes of stars and bars. Its an editor key-comb, bam, box appears, and you fill in your comments.
When they became MY shop, (as they often did) for new code I imposed my reformatter and macros, and on rare occasions I'd even run existing systems through our newer reformatting. But I'd seldom reformat comment structure. And it was all private code, not a community project.
No, you are mistaken. I've always had this sig.
(Score: 2) by Username on Tuesday July 12 2016, @06:35PM
I’d just do the lazy copy paste and add 1 to the end of the name.
(Score: 5, Funny) by kurenai.tsubasa on Tuesday July 12 2016, @03:28PM
Instead of epic rant email contained well-reasoned request. Would not read again. A---------------.
(Score: 5, Interesting) by JNCF on Tuesday July 12 2016, @03:48PM
I'm sure that looks really nice if you
are out of your mind on LSD, and have nothing better to do than to
worry about the right alignment of the asterisks.
Anybody else get the feeling that Torvalds is not an experienced traveller? You can code competently on a microdose, and it at least feels like you can focus better and juggle more variables mentally. Take more and you will become significantly less productive (nontrivial bug-finding becomes ridiculous somewhere around a mere two tabs), but the asterisks will not be the most interesting part of your code base. Interfaces get really interesting really quickly. To me, Torvalds' comment comes off as ignorant. Maybe he's just had very different experiences with LSD, but I doubt he's had any.
(Score: 0) by Anonymous Coward on Tuesday July 12 2016, @04:37PM
I agree, worrying about the right alignment of asterisks would be more of a methamphetamine problem than an LSD one.
(Score: 2) by JNCF on Tuesday July 12 2016, @04:43PM
I lack personal experience, but I have it on good authority that amphetamines make you a more productive coder. Everything has its limits, I'm sure.
(Score: 2) by HiThere on Tuesday July 12 2016, @07:47PM
Well...since meth is a stimulant, and so is caffeine, and many folk swear by coding on caffeine, it's plausible. I wouldn't go any further than that.
Javascript is what you use to allow unknown third parties to run software you have no idea about on your computer.
(Score: 4, Interesting) by JNCF on Tuesday July 12 2016, @08:12PM
I knew a guy who swore by it. I knew a guy who knew a guy who supposedly had great success coding on cocaine. I've never done either, but I try not to judge other folks' preferences in mental states until I've seen how the specific individual handles their cocktail of choice. The most obvious examples of drug users are often the worst. If you see somebody shambling around scratching their face in public, they probably aren't producing anything of value from their use of stimulants. If somebody is working remotely and hammering out code, you probably won't know what their choice of stimulant is unless they decide to tell you (and they won't, unless they think you'll be cool and nonjudgmental). Even caffeine is probably harmful on a long-term basis if taken too often, but it's certainly a short-term godsend.
This reminds me of an oft-repeated story about the absurdly prolific mathematician Paul Erdős: [untruth.org]
Erdős's friends worried about his drug use, and in 1979 Graham bet Erdős $500 that he couldn't stop taking amphetamines for a month. Erdős accepted, and went cold turkey for a complete month. Erdős's comment at the end of the month was "You've showed me I'm not an addict. But I didn't get any work done. I'd get up in the morning and stare at a blank piece of paper. I'd have no ideas, just like an ordinary person. You've set mathematics back a month." He then immediately started taking amphetamines again.
(Score: 1, Interesting) by Anonymous Coward on Wednesday July 13 2016, @04:08AM
On lower doses, yeah, it might help make you more productive, but on higher doses your run the risk of getting caught in what's called a "loop", where you get stuck doing the same thing over and over and over and over again, because it never quite feels "right", so you keep redoing it and redoing it and redoing it, basically until you come down.
(Score: 0) by Anonymous Coward on Wednesday July 13 2016, @09:04AM
This is incredibly creepy because this is pretty much how I operate normally, starting over and over and over, because it isn't perfect.
Maybe perfectionism has a chemical component? Food for thought and investigation!
(Score: 2) by JNCF on Wednesday July 13 2016, @05:01PM
Yeah, I'm not saying that meth isn't a really-fucking-scary drug. There's a reason I've never tried it (a number of them, actually). I could see the asterisk thing being a reasonable side-effect of prolonged/heavy meth use -- I'm not saying it is, but I'm not saying it isn't. I've only seen that mental state from the outside. It's super scary, but if somebody else wants to walk that tightrope I wish them the best of luck.
(Score: 0) by Anonymous Coward on Wednesday July 13 2016, @05:30AM
https://xkcd.com/323/ [xkcd.com]
(Score: 3, Funny) by Bot on Wednesday July 13 2016, @06:12AM
If he had been an experienced traveller, he'd have written systemd instead.
Account abandoned.
(Score: 1) by letssee on Wednesday July 13 2016, @08:52AM
People who do LSD *think* they can function normally. Everybody else knows they have irreversibly turned into religious assholes who have "seen the light" (damaged their brain, they mean).
/rant
(Score: 1, Funny) by Anonymous Coward on Tuesday July 12 2016, @03:50PM
I thought the boxes I added to existing comments made things way more readable.
(Score: 2) by FatPhil on Tuesday July 12 2016, @10:23PM
Which reminds me, I never finished writing the song which had a refrain containing "Is this patch just another bad patch in my series of bad patches".
Great minds discuss ideas; average minds discuss events; small minds discuss people; the smallest discuss themselves
(Score: 1, Interesting) by Anonymous Coward on Tuesday July 12 2016, @04:02PM
Come on, if you like a style, then it force via code. Force the use of LINT or other tools at check in that insures correct form is used.
I personally like the following. Brings your eyes right to it. Specially is left handed languages that is hard to pick-out code from comments. Been using for more than 40 years. IBM CL code used this same comment structure.
(Score: 5, Insightful) by tibman on Tuesday July 12 2016, @04:50PM
If you need banner comments to grab someone's attention then i think there is an overuse of worthless comments in the code. All comments should be important enough that people read them. Comments to explain what variables mean are an indication that the variables have nondescriptive and bad names. When i run across those i often camelCase the comment and rename the variable to the comment (thus removing the worthless comment and improving code readability everywhere that variable is used).
I also see banner comments used to divide files into sections. In those cases i section the file into multiple files along those comment boundaries and use the comment to provide the file (and possibly class) name. If you have two distinct families of functions (and especially member variables) inside one class then you really have two classes.
Banner comments are a code smell, imo : )
PS: old IDEs are excused from my criticism, of course. Especially excused when the display only has one color, lol. Even good text editors have had syntax highlighting for decades (though no refactor tools, obviously).
SN won't survive on lurkers alone. Write comments.
(Score: 0) by Anonymous Coward on Tuesday July 12 2016, @05:45PM
Agreed, comments should be located near the relevant code so no searching or eye grabbing really needed. I sometimes tag a line with asterisks for the visual indicator in CSS files just because there aren't function calls or similar grouping separators.
(Score: 1, Informative) by Anonymous Coward on Tuesday July 12 2016, @05:55PM
Especially excused when the display only has one color
Even on my amber and green monochrome CRTs we had syntax highlighting thanks to there being multiple levels of brightness, uniform hue though it may be.
(Score: 4, Interesting) by frojack on Tuesday July 12 2016, @07:26PM
Even good text editors have had syntax highlighting for decades (though no refactor tools, obviously).
Syntax highlighting seldom does anything with comments.
I've modified all my syntax highlighting scripts to show comments in a light shade of gray, to make it LESS intrusive when reading the code.
Spot on about explaining variable names in comments. Just poor form.
Other findings of mine:
Comments often are misleading. People patch the code, and all too often forget about the comments.
Comments become misplaced because people add code patches, and comments can thusly drift away from were they were intended.
If you have to explain it, you are doing it obtusely, even if not wrongly. Write simpler code. (It often compiles to tighter code as well).
No, you are mistaken. I've always had this sig.
(Score: 2) by Nerdfest on Tuesday July 12 2016, @11:42PM
Damn, I'm pleased that both you and the GP are on my "friend" list. You're obviously *actual* programmers that think about what you're doing as opposed to following the "everything must be commented" silliness. I strive for zero comments, and I'm hoping that eventually I'll be a good enough programmer to get there, although I think I'll need a little help with better languages.
(Score: 2) by JNCF on Wednesday July 13 2016, @01:23AM
I strive for zero comments, and I'm hoping that eventually I'll be a good enough programmer to get there
I agree with this general sentiment, but I think that there are going to be times when there is unexpected behavior in an external API that should be explicitly stated in plain English to a newcomer looking at the wrapper code. Do you disagree? I see this is the most valid use case for comments, and while I begrudgingly use comments outside of this context I view them as sub-optimal methods of explanation that I really shouldn't be using as crutch. I always look for alternative ways of phrasing the code first. When describing the strange behavior of somebody elses API, I feel no such guilt; the only alternative I see is replacing the API.
(Score: 2) by Nerdfest on Wednesday July 13 2016, @02:08AM
Nope, I completely agree. Zero comments is a goal that might be achievable if *everything* is perfect, including external interfaces, etc. In reality it's quite unlikely to ever happen.
(Score: 0) by Anonymous Coward on Wednesday July 13 2016, @10:44AM
So how would you replace any of the following comments by code?
(Score: 3, Funny) by Post-Nihilist on Wednesday July 13 2016, @01:24AM
//TODO: That comment is as
Be like us, be different, be a nihilist!!!
(Score: 1) by letssee on Wednesday July 13 2016, @09:03AM
> Comments often are misleading. People patch the code, and all too often forget about the comments.
Very true.
That's why I actually prefer c++ style end-of-line comments, even though they're ugly. there's a slightly better chance the comment gets edited when the line gets edited.
Obviously this only works as long as the comment only is about that single line.
I very much prefer self-documenting code with ridiculously long variable names. But even then stuff gets messed up.
It is very difficult to keep large projects understandable over time, maybe the most difficult thing in coding.
(Score: 2) by darkfeline on Wednesday July 13 2016, @08:45PM
>Comments often are misleading. People patch the code, and all too often forget about the comments.
>Comments become misplaced because people add code patches, and comments can thusly drift away from were they were intended.
Whoever does the code reviews is incompetent. Any commit that changes the code without fixing up the comments should be rejected without further consideration.
Note that I'm also including documentation strings in the "comments" category, and the reality is that sometimes there is poorly designed code that cannot be fixed immediately or at all, and adding an informative comment is much better than every future developer wasting a few hours re-figuring out a section of code.
Join the SDF Public Access UNIX System today!
(Score: 2) by frojack on Thursday July 14 2016, @05:45AM
Chuckle....
Desk jockey still believe code reviews happen in real life....
No, you are mistaken. I've always had this sig.
(Score: 2) by darkfeline on Friday July 15 2016, @08:48PM
I apologize for having worked at places where my code was reviewed and I reviewed my coworkers' code before they could be checked in?
Join the SDF Public Access UNIX System today!
(Score: 2) by Post-Nihilist on Friday July 22 2016, @01:09AM
I wished I could get my code reviewed..... I ask for review but no one wants to review my code... they they are not qualified to reviewed my code. Yet I continually get asked to review other peoples codes. The closest thing to a code review a can get is a spell and grammar check, everyone at work is always happy to correct my email, comments or documentations as I suck at spelling and grammar in french and english .... !!!! but my code they never want to ... I wish I worked somewhere where I am not the guru but the work condition, the professionnal association (a fancy white collard union) and the life outside a big city is worth it.....
Be like us, be different, be a nihilist!!!
(Score: 2) by darkfeline on Friday July 22 2016, @01:55AM
They should still review your code anyway. Reviewing code is a mandatory part of the job of a software engineer/developer, not optional, just like making sure no surgical tools are left inside the patient is a necessary part of the job of a surgeon/nurse.
Of course, software is not regulated (yet?), so you can't sue a company for being willfully negligent.
Join the SDF Public Access UNIX System today!
(Score: 0, Disagree) by Anonymous Coward on Tuesday July 12 2016, @07:43PM
If you have comment each line, WHY???
1) The code tells it all, period. so no mismatch between code and comments.
2) That means using real names, not ALPHA, BETA, GRAMMA for variables, functions, routinue, classes, ... IE no need for comments there.
3) Comment blocks are before a block of code to introduce the code and it goal. Not to show how smart you are in writing tricky things.
4) routines should "never" go over 50 lines (was 2 screen pages ~44). YES, you will break the rule on RARE occasions. But too big means, it cannot viewed and understood by just viewing. Do care if BASH Script or Cobol or any other language.
(Score: 0) by Anonymous Coward on Wednesday July 13 2016, @09:04PM
No, it doesn't. [soylentnews.org]
(Score: 0) by Anonymous Coward on Tuesday July 12 2016, @06:05PM
I hear a "KREEEEEK" in my head when i see that sort of stuff. Such a fucking waste of time and nerves to do something like that.
This is enough:
/*
pla pla pla pla pla
Yak yak yak
*/
I don't want to add even those asterisks Linus want at the beginning of the line. Waste of time.
(Score: 2) by JNCF on Tuesday July 12 2016, @06:51PM
I associated those vertical lines of asterisks with automatically generated documentation. I actually like them in that context, but I slightly dislike them outside of that context because I think it would be nice to reserve the pattern for that specific use. Other patterns would work just as well, but I've seen this one used by multiple doc generation tools already. With syntax highlighting, I'm not convinced that the pattern stands out significantly more than regular multi-line comments. The extra maintenance cost is negligible, but existent.
(Score: 2) by HiThere on Tuesday July 12 2016, @07:53PM
OK, since everyone's doing it...
/** This is my comment style.
* continued here.
* @param var appropriate stuff.
*/
Javascript is what you use to allow unknown third parties to run software you have no idea about on your computer.
(Score: 1) by petecox on Wednesday July 13 2016, @02:07AM
Well yep that served java well enough and editors such as Eclipse made formatting easy to enforce via a config file.
Any medium size meticulously managed project I've worked on has adopted a style guide, distributed to new hires on their first day.
So I'm surprised that in 25 years benevolent dictator Linus never adopted a policy of not accepting commits that weren't pretty printed according to guidelines.
These things can be automated and seems fairly low hanging fruit to any new kernel contributor.
(Score: 2) by HiThere on Wednesday July 13 2016, @06:44PM
Well, actually I use it with Doxygen and C, C++, or Python. (Details differ, but the format's the same.) With D I use it's built in document comments...the output isn't as nice as Doxygen, but it understands the language better.
OTOH, with Lisp, Scheme, or Ada the commenting system was sufficiently bad that it was one of the reasons I dropped the language. (And you'll notice that for Python I don't use Sphinx. I find that unusably bad for program documentation, however good it may be for document creation.)
Different people seem to use program documentation in different ways. It's my preference to never need to read the embedded documentation again, but rather to use reformatted versions. Doxygen is good for that, and Java clearly has some way to do this. Actually, so does Python, and if the program is going to be entirely Python I'll use pydoc, though the html it generates is a bit garish.
So if you use documentation the way I do, the internal layout isn't significant, and thus I prefer a style that conserves vertical space. Some people, however, like to read the documentation as embedded in the code, while I only do that while I'm in the process of writing or editing the routines.
But the real point is that each project has a standard that should be adhered to.
Javascript is what you use to allow unknown third parties to run software you have no idea about on your computer.
(Score: 2) by HiThere on Tuesday July 12 2016, @07:50PM
I prefer the comments that Doxygen likes. If Doxygen likes them, I'm likely to never look at the originals. And that's the way I like it. If the comment isn't enough, what I'll look at is the code, and except when I'm first writing it I consider that a failure.
Javascript is what you use to allow unknown third parties to run software you have no idea about on your computer.
(Score: 0) by Anonymous Coward on Tuesday July 12 2016, @08:25PM
I used to do it like that. Then after a few years when I started writing thousands of lines of code at a time, it became a pain to edit them. I like to use vim and sed for writing code and small scripts and other programs too to generate "boiler plate." The simpler the better.
(Score: 3, Informative) by Thexalon on Tuesday July 12 2016, @04:12PM
Waaaa! Linus said a mean thing to me!
Look, it's his project, he can impose whatever standards he chooses on code, comments, and so forth. That's what being a BDFL involves. If you don't like it, then try and start a fork where you can do whatever you want.
The only thing that stops a bad guy with a compiler is a good guy with a compiler.
(Score: 5, Informative) by GungnirSniper on Tuesday July 12 2016, @04:12PM
Linus, as usual and if cranky, is absolutely correct here. Far too often we get in the habit of quick-and-dirty work, skipping comments and readable formatting because we often consider bits of code as either one-and-done or I'll-fix-this-later hodge-podge. Yet for professional-level work, that ensures at the very least it will take longer to re-read and understand, particularly if someone else takes on the work. We've all inherited crap projects and had to untangle spaghetti code, so for the sake of being a real profession, let's aim for higher than "it compiles" or "it works". We could learn from doctors and lawyers, and it isn't just the guilds that keep their reputations high.
// I comment the hell out of my work,
// and have been complemented on it years later.
Tips for better submissions to help our site grow. [soylentnews.org]
(Score: 1, Touché) by Anonymous Coward on Tuesday July 12 2016, @04:30PM
He's right about everything except the LSD.
(Score: 3, Funny) by Anonymous Coward on Tuesday July 12 2016, @05:46PM
I [...] have been complemented on it
Can't decide if typo or legit.
(Score: 0) by Anonymous Coward on Tuesday July 12 2016, @07:54PM
I [...] have been complemented on it
Can't decide if typo or legit.
That depends on the number of times complemented.
(Score: 0) by Anonymous Coward on Tuesday July 12 2016, @06:17PM
Life is not too bad if the problem can be fixed with a pretty printer.
My grandfather was the nicest guy you could know until he started getting upset about little things just before Alzheimer's.
It takes extra cpu cycles to be nice.
Some folks never have those cycles.
No one could have made Linux the thing it is without those extra cycles.
Hopefully this isn't a sign of things to come.
(Score: 0) by Anonymous Coward on Tuesday July 12 2016, @07:50PM
UGH. Pretty printers suck.
(Score: 4, Interesting) by butthurt on Tuesday July 12 2016, @06:58PM
It used to be that when Linus Torvalds started focussing on superficial matters like this, it was a sign that the next Linux version would be especially stable. I don't know whether that still holds true.
(Score: 3, Informative) by butthurt on Wednesday July 13 2016, @12:20AM
Thanks for the up-mods but I may have been mistaken. I looked for mailing list messages on the topic. After seeing this one from Torvalds, I think I misremembered:
-- http://lkml.iu.edu/hypermail/linux/kernel/0302.2/0404.html [iu.edu]
(Score: 2) by dltaylor on Tuesday July 12 2016, @07:37PM
While Linus isn't always correct, he usually is, and this time, too. When you play in someone else's sandbox, you play by their rules. Regardless of how horrible you find Microsoft's coding style, that's what you use, because the next person who works on, or even refers to, your code doesn't need to get the cognitive dissonance of your "cute" style. Some thing here; there is a common kernel style and the clowns who insist on right hand asterisks are just mentally masturbating, wasting their time and the time of everyone else who ever looks at that bit of silliness.
(Score: -1, Flamebait) by Anonymous Coward on Tuesday July 12 2016, @07:37PM
When the kernel security is swiss cheeze but FUCK those grsecurity guise, right. They don't know what they're doing, right?
Oh and don't mind the hardware backdoors in Intel, AMD, and Arm processors. It's all good.
Comment style, that's what matters.
And women in tech.
And fat ass "wives"
Fucking git.
(Score: 0) by Anonymous Coward on Tuesday July 12 2016, @09:00PM
Most of this can be fixed by script, it really doesn't matter. Be glad there are comments at all, I've seen too many important pieces of code with fucking no documentation.
(Score: 2) by pgc on Wednesday July 13 2016, @02:08PM
Well that is what Herbert gets for saying that the Crypto API adheres to the network stack standard, so unless they change *that* ...
what did he expect Linus to respond?
(Score: 1, Informative) by Anonymous Coward on Wednesday July 13 2016, @02:37PM
For the record, Ingo Molnar requested the change because the networking stack commenting style is inconsistent (even within networking) and due to a typo 20 years ago. Linus is just helping a bit steering the discussion to a no-nonsense direction.
See [1] [iu.edu]
> > > /* Compute how many bytes to copy from user buffer into
> > > * extra block
> > > */
please use the customary (multi-line) comment style:
/*
* Comment .....
* ...... goes here.
*/
specified in Documentation/CodingStyle.
And justified its request in a follow-up email [iu.edu]. In short, networking mixes both commenting style and treat the ugly one as gospel for no other reason than Alan Cox making a typo 20 years ago.