Slashdot Mirror
If the Comments Are Ugly, the Code Is Ugly
itwbennett writes "What do your comments say about your code? Do grammatical errors in comments point to even bigger errors in code? That's what Esther Schindler contends in a recent blog post. 'Programming, whether you're doing it as an open source enthusiast or because you're workin' for The Man, is an exercise in attention to detail,' says Schindler. 'Someone who writes software must be a nit-picker, or the code won't work ... Long-winded 'explanations' of the code in the application's comments (that is, the ones that read like excuses) indicate that the developer probably didn't understand what he was doing.'"
An explanation may be long if it is explaining something complex that the code is doing. A long-winded comment may also be a precise one, rather than a general one: rather than an excuse, this may be an explanation.
-- IANAL, this isn't legal advice, and definitely isn't legal advice for you. Also, Squee!
Comments are good for many reasons:
1. Showing the next person what you were doing.
2. When you have to explain what you are doing, it helps you to discover possible errors in your code. Particularly logic errors.
3. It helps you if you have to come back and look at it in a few years so you will immediately have an explanation of what you were doing.
Of course for those of us who code perfectly the first time, they aren't really needed. :-)
Long-winded 'explanations' of the code in the application's comments (that is, the ones that read like excuses), indicate that the developer probably didn't understand what he was doing.'
Or that he's forced to work with people that don't.
Comments exist NOT to explain the existing code, but to explain all the other code that could have been written, but wasn't. They also point to things like test cases (which if your language doesn't suck, you can put in line), and explanatory standards documented elsewhere.
Don't piss off The Angry Economist
For me, it is bad spelling in variables and such. Or correct but "alternative" spellings - like honor_no_cache vs. honour_no_cache
Working with fellow students in a group (with one student being from England) brought this out, and in general poor spelling - category vs. catagory, etc.
Fortunately mostly fixable with find/replace, but still a bear to deal with.
Don't blame me, I voted for Kodos
Many people who write code are not native English speakers. it would be silly to expect their code or comments to read like a Thomas Hardy novel.
In addition, some of us write comments first and then fill in the code. Often, in fact quite often, the code evolves past what the comments say.
Someone who wastes time producing grammer-school perfect comments is wasting time that could be better used by making the code itself better.
I sometimes write code for number theory algorithms. Often short-cuts and little speed ups have long proofs to justify why they work. If I expect the code to be used/read by other people I'll often include these explanations (and so I don't need to bother convincing myself later if I look at the code a year later). There's nothing wrong with long comments. Moreover, given a negative attitude towards long comments, many bad programmers will likely simply respond by not commenting their code at all. That's not good.
Comment removed based on user account deletion
English is not most people's first language. Be glad they want to write comments in English at all.
const int one = 65536; (Silvermoon, Texture.cs)
SJW, n: "Someone I don't like, and by the way I'm a fuckwit" - AC
I once coded a function that varied depending on what quadrant (+x,+y; -x, +y; -x,-y; +x,-y) it was in. I couldn't get it to work right in the second quadrant, but finally got it working by chance and said so in my comments. The code worked, but I didn't understand why and said so. Is that bad coding? It worked!
If you don't understand why it worked, then you don't know how it worked. Consequently, you have no idea under what circumstances it won't work. Unless your unit tests enumerated every possible set of inputs, you don't actually know it worked. Just because code works for some inputs doesn't mean it works.
Hey, thanks for making that comment!
If Pandora's box is destined to be opened, *I* want to be the one to open it.
If I have a long comment explaining "magic", 99 times out of 100 it's because I'm being forced to interface with a bad API which THAT CODER didn't properly understand. Glaring errors in the documentation, unexpected outputs, unexpected hangups ... these are my duty to comment about. Of course I don't understand why the API is malfunctioning ... it's a BLACK BOX. My employer might be too much of a cheapskate to purchase product support to troubleshoot the API. Or the vendor might charge outrageous support fees for their mess ups. I cannot switch to a different API, because I do not have the authority to make that decision.
My comments are self-defense when backed up against the wall. It does nothing to gauge my programming ability.
"Love heals scars love left." -- Henry Rollins
Everybody has their little "pet signposts" that they use to make wider conclusions. Although there may be small truths to some of them, relying on weak correlations is generally a dangerous way to make conclusions. Good programming involves a wide variety of skills. To focus on a few narrow factors does a disservice to this fact.
For example, I sometimes put in long comments because the business rules themselves are convoluted. Programming logic cannot make a silk purse out of a sow's ear. Ugly biz rules are ugly biz rules and are not explainable in just a few lines. It's outside of the scope of my duties to clean up the business practices (other than pointing them out sometimes).
I agree that long comments can serve as a yellow alert to stop and think. But that does not mean that all long comments are inherently a sign of flawed code. The author is being a drama queen via exaggeration. And perhaps it's part piety: I am a careful comment-speller, so you should be also.
Table-ized A.I.
In fairness to Ritchie, he was programming on bare metal and breaking new ground. OS level code talking directly to hardware can get pretty grotty because of all of the vagaries that can be going on that aren't readily apparent without the device manual and some experience.
At least he did comment it, and there was enough information in there to at least give context for what he was doing.
Cheers
Lost at C:>. Found at C.
you often wind up using certain functions heavily that reveal themselves to have strange quirks
since these functions are effectively black boxes that your average developer has no legal ability to understand deeper, you have to leave it at that
blaming the coder for being unable to know why something works in such a situation would be fundamentalist in attitude on your part
yes, you should understand everything you write in code, but you also need a job to put food in your mouth and a roof over your head. not everyone can be a greybeard learning the deep zen of a true coder in a completely open source environment
you should therefore show some leniency for the journeyman programmer trying to pay his bills, who has to work with black box functions under deadline out of necessity, not choice
in such a situation, it is perfectly reasonable to hack at the code until it works, then quietly walk away, unable to know why you made it work. in microsoft land, since the functions you are working with are closed source, you can't blame the programmer for this status quo
intellectual property law is philosophically incoherent. it is your moral duty to ignore it or sabotage it
Frankly, morons like you are the reason the industry is laughed at by other, more formalized disciplines. Could you imagine what we'd do to a bridge builder who just tacked stuff on until it kinda sorta stood?
Easy on the self-righteous indignation. I'll stay with your bridge analogy.
The simple truth is there are few software industry segments written to your 'bridge building' requirement. You want maintainable software. Your boss wants maintainable software. At the C-level meetings, they want faster and cheaper.
Nowhere in "faster and cheaper" is there room for your mythic "formalized discipline." I'm not sure if you are after the kind of societal reverence a doctor or lawyer gets or what. If that societal respect is you want, get a JD.
Best case scenario, you are well-known and respected by your peers and the person to whom you report.
http://www.maxineudall.com/2010/02/should-economists-be-sued-for-malpractice.html
From 30 years of developing software, I've found time and time again that it actually does seem that people who don't know or care about the difference between "their" and "they're" are also too sloppy, unintelligent or just not anal enough to write clean, supportable and robust code.
However I feel we do need to make more allowance than the article's author did for people who did not learn English as a first language.
I'm impressed - 30 years! Wow!
In my measly 15 years of experience, I've had to spend many long hours meeting deadlines that some salesman made for us to make the sale. Of course, management backed up the ridiculous deadline because "if the salesman didn't say it could be done, some other company would have and we wouldn't have had the business!' So, said salesman makes his 6 figure commission and us coders are working 80+ hours a week to meet the ridiculous deadline - which happens frequently. Now, when I'm tired, fearing for my job, and trying to design and code on top of all that, the last thing I'm worried about is making sure I don't confuse "they're" with "their" or with "there". I'm worried about being productive, because if I'm not, they'll send the work to a country where they don't even speak English; let alone actually even bother to comment their code.
Personally, I'd rather have something than nothing; regardless of how poor the spelling is or the grammar. It's a software comment, not a dissertation.
But that's been my measly newbie experience.
It's NOT me! It's the meds! I'm on 1000mg of Fukitol.
>> That's also why I don't comment my code.
This is a good practice. Comments very seldom keep up with changes in the code base, so more often than not, they end up being misleading at some point in the future.
That's complete crap. I've heard this argument before, that by not putting in comments you force the next guy to read all the code. That of course assumes that your code is so clean, obvious, and readable that the next guy will be smitten with your mad skillz.
I would say that it's a reliable indication of extreme ego and lack of skills when a programmer eschews comments entirely.
Comments serve as an aid to understand not only the code but the problem domain addressed by the code. It's a means of recording knowledge that the code doesn't make readily apparent. Reticence to comment indicates laziness and perhaps even a lack of understanding as to why the code worked in the first place.
*** *** You're just jealous 'cause the voices talk to me... ***
Perfectly working, syntactically and logically correct code can be utter crap if it is not maintainable.
Years ago, a very smart man told me that I was not writing code for the compiler, I was writing code for the next poor slob that had to work on it. Let's face it, most source code is going to be subject to rework or maintenance over its life span, so let's do what we can to make that next developer productive. The key to this is reasonable commenting.
One of the best ways I know of to teach developers to write maintainable code is to have them do support and maintenance for a while. Developers learn quickly which styles work for maintenance, and which ones don't.
As far as I am concerned, source code needs to look good as well as compile. So I would go one step beyond TFA to say that style, indentation, proper symbol names, use of constants where appropriate, and (yes) proper commenting are all good indicators of quality in source code.
there are 3 kinds of people:
* those who can count
* those who can't
"You" - who formally prove your code, comment it, and make sure it works right - are called at 2 am in the morning to fix code that "He" wrote. "He" is now your boss, because:
Programmers beware: the meticulous, but correct, programmer is a valuable asset to the company; the sloppy but fast programmer is his boss.
The society for a thought-free internet welcomes you.
Worst: Originally erroneous or out of date therefore erroneous comments. Actively destructive to comprehension of the program, and once detected, causes all other comments in the program to be rejected as untrustworthy and worse than useless. "Comment Bug".
2nd Worst: No comments - indicates the developer either does not understand the purpose or method in their madness, or is lazy and sloppy. Either is very bad.
3rd worst: Redundant comments: /** Gets the Foo! */ Foo getFoo() See Java api documentation for prime examples.
I would much rather read a long rambling philosophical comment that was essentially correct and did add some information than to deal with any of the above slackerware.
Where are we going and why are we in a handbasket?
UNIX is simple, but you have to be a genius to understand the simplicity.
Don't kid yourself. It's the size of the regexp AND how you use it that counts.
Whoever is criticizing grammar in comments obviously never had to look through legacy code and ask him/herself "WTF was this developer thinking?!" Or better yet, looking at one's own code written five years earlier and asked him/herself "WTF was I thinking?!" In those cases, any comments at all will provide clues.
We should be encouraging coders to use comments _at all_, not giving incentive to shortchange it because they are going to be graded on stuff the compiler ignores. Any coder stuck with making changes to old code will be very thankful to see long-winded comments.
Let's not forget that code is read many more times than it is written. Yes, it would be nice to have precise comments that tell all. But if a coder wants to go into detail then friggin let him, to suggest otherwise is just dumb.