7053884
story
Comments: 660 +- Developers: If the Comments Are Ugly, the Code Is Ugly on Monday November 16, @11:29AM
background: url(//a.fsdn.com/sd/topics/topicprogramming.gif); width:80px; height:48px;
programming
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.'"
Related Stories
Executive ability is prominent in your make-up.
All trademarks and copyrights on this page are owned by their respective owners. Comments are owned by the Poster. The Rest © 1997-2010 Geeknet, Inc.
The comment may also be complex.. (Score:5, Insightful)
Re:The comment may also be complex.. (Score:5, Funny)
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!
Parent
Re:The comment may also be complex.. (Score:5, Insightful)
It worked!
Are you sure about that? Did you really have enough of an understanding of the conditions to make that statement?
Chances are, it worked in the subset of cases you understood, and maybe in the subset of cases that the app needed at the time. In the future, though, all bets are off ...
Parent
Yes, that's bad coding (Score:5, Insightful)
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.
Parent
Re:The comment may also be complex.. (Score:5, Insightful)
The code worked, but I didn't understand why and said so. Is that bad coding? It worked!
Yes. It's bad coding. Very very bad coding. And, no offense, but it indicates intellectual laziness on your part.
Any developer worth their salt would spend the time to understand *why* their code is mysteriously working, rather than just throwing up their hands and moving on, as a) it might be working for your test cases but still be incorrect, and b) anyone coming along later will be hosed, as if you couldn't understand it, there's a good chance they won't be able to, either. And of course, d) any developer worth their salt *wants* to know why their code is working, simply because it's interesting and *part of their job*.
Parent
Re:The comment may also be complex.. (Score:5, Funny)
Unless your code is running in IE5 or IE6. Then you get it to work by chance, and do not ever touch it again.
Parent
Re:The comment may also be complex.. (Score:4, Funny)
On the basis of your username, I'm perplexed as to why you somehow failed to properly letter the items of your list. Perhaps "c) ???" should have come in front of "d) Profit!" (well, a rather long and windy version of "profit", but boils down to it basically)?
Inb4 comments about my failure to count down from 5.
Parent
Re:The comment may also be complex.. (Score:4, Insightful)
And while you're spending your time figuring out why something that isn't broken works, he is coding something that you aren't coding at all. Sure, coding until it passes isn't the ideal, but it's a whole lot better than not coding at all (you).
Bullshit. Software development isn't just about "coding". It's about producing software that's functional and maintainable. "Hacking it until it works" is completely antithetical to those goals.
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?
Parent
Re:The comment may also be complex.. (Score:5, Insightful)
Construction, even of your vaunted bridges is filled with hacks carried out at all levels of the build.
Oh please. Inexactitude is *not* the same thing as not understanding why something works at all. We can build miles-long bridges *specifically* because we understand the underlying physics, and anyone who built a bridge without understanding the physics of why it stood under load would be drummed out of the industry.
Software development typically isn't engineering. It's usually a business of maximizing productive features versus minimizing cost and time. Rarely is the answer to further investigate working code.
Sorry, that's crap. Any code complex enough to be difficult to understand is specifically the code that requires extra care and attention to ensure it's correct. If you don't understand why your complex algorithm works, you need to spend more time to understand it, as the odds are extremely good that it's a) not correct, and b) not maintainable.
Parent
Roman Bridges (Score:5, Interesting)
Oh please. Inexactitude is *not* the same thing as not understanding why something works at all. We can build miles-long bridges *specifically* because we understand the underlying physics, and anyone who built a bridge without understanding the physics of why it stood under load would be drummed out of the industry.
I am assuming you refer to the modern physics that we are all so proud of. Let me tell you that in Europe, whenever you get a real serious flooding on a major river, only one kind of bridge survives with no bruises at all: Roman bridges. They are 2000 years old, but they're still up. The crap we're building today won't be up in 2000 years, I can bet on it. Look at the mess with the bay bridge, down twice in 50 years!!!! Ah ah ahah! Kuddos to modern engineering.
That would be because the Romans had some engineering, but not the equations we have today, so they over-engineered their bridges for safety because they knew they couldn't calculate the exact, optimal configuration for the expected loads and stresses. Over-engineering is a good thing if you don't have to account to the bean-counters. The George Washington Bridge across the Hudson River was also over-engineered because they didn't know the exact tolerances, and it has held up rather well.
Parent
Re:The comment may also be complex.. (Score:5, Insightful)
The reason the 2000 year old Roman bridges survive is because all the shitty ones were destroyed hundreds of years ago.
Parent
Re:Blame Game (Score:5, Insightful)
Nowhere in "faster and cheaper" is there room for your mythic "formalized discipline."
Wait... suddenly understanding your own code is "formalized discipline"? Might I suggest your standards are simply too low? Because, in my mind, understanding your own code is in the category of "basic competency".
Parent
Re:The comment may also be complex.. (Score:5, Insightful)
And while "he" is getting called at three in morning 2 years later to fix a crazy bug that has stopped all business, due to a new use-case being introduced that mysteriously breaks that function, "you" is now coding on a new project, using sound development techniques (including understanding how code works while "you" writes it), making the company new money.
Parent
Re:The comment may also be complex.. (Score:5, Insightful)
And while you're spending your time figuring out why something that isn't broken works, he is coding something that you aren't coding at all. Sure, coding until it passes isn't the ideal, but it's a whole lot better than not coding at all (you).
Coding two routines by coincidence is not more productive than coding one routine properly.
Parent
Re:The comment may also be complex.. (Score:5, Insightful)
Parent
Re:The comment may also be complex.. (Score:5, Insightful)
I've had to maintain code originally written by people with that attitude. To put it politely, I wish they'd switched careers to something besides computer programming; it would have saved everyone a lot of work, cost overruns, budget overruns, and pissed off a lot fewer customers.
If you don't know what the hell you're doing, you're not going to do it very well. Code that "works by accident" is very fragile and breaks easily and is a triple bitch to maintain, because if you don't know what you wrote, I have to pretty much reverse engineer it from the source code to figure out what you *actually* wrote vs. what you were supposed to write--then I usually end up re-writing it from the original requirements to do what it should have been doing in the first place, because the existing code is such a mess.
Parent
Re:The comment may also be complex.. (Score:4, Insightful)
I agree with cream wobbly that it's good prototype code but bad release code. On the other hand it's okay with me that you explained the difficulty in the comments because that fulfills the purpose: You're communicating with the next developer who looks at the code.
If you managed to get it to work (you think, anyhow), it may still be buggy; and the "Well, I THINK so..." in the comments will be an arrow to "probable source of application meltdown" for someone who comes in to debug.
There's a difference between writing a good explanation that happens to be long, and a rambling list of excuses. Yours sounds like the former. IMHO.
Parent
Re:The comment may also be complex.. (Score:5, Insightful)
In your example, the code you got working for -x, +y may not have been "Good", but if it passes the Unit Tests, then how is it really bad?
How is it bad?? Christ, the metric for "good" code isn't that it simply "works". It also needs to be readable, comprehensible, and maintainable. If you can't understand how your own code works, it's bloody obvious it fails on at least one of those metrics.
Besides which, unless you are 100% positive that your unit test covers *all* cases, the fact that your code passes tells you nothing about it's correctness.
You know, back in my university days, we used to scoff at the morons in the labs who would, quite literally, randomly hack their projects until they worked. I never dreamed that some would consider that a valid development methodology out in the real world. Apparently there *is* a dark side to a high-quality unit test suite... it gives idiots a false sense of security and justifies their idiotic development practices.
Parent
Re:The comment may also be complex.. (Score:5, Insightful)
That kinda presumes that the unit tests are good, doesn't it? Which means that somewhere, somehow, somebody has to know what problem they are trying to solve.
Defining 'good enough' is really tough. I've seen perfectionists get bogged down, but even more often, I've seen folks that invoke the 'it's good enough' mantra as a cover for sloppiness and incompetence.
Parent
Re:The comment may also be complex.. (Score:5, Insightful)
I have known several people who point out that if it really does require that complicated of an explanation, you might need to re-factor your code and make it less arcane. Of course, not everything can be simplified to the point where it's obvious when you read it, but I've definitely seen a lot of code that could/did benefit from changing it to make it more straight-forward and readable.
In general though, I agree with the article -- I've known more than a few developers who barely if ever comment code, and claim that it should be obvious from the code. As such, their comments (what there are) tend to be fairly random and not helpful. I once saw a comment that said "die lamer die" with no explanation whatsoever. "Add 1 to count" is also fairly useless.
Me, I always write the comment for a function/method before I've started writing the body of the method. Because, even if it's just me maintaining the code, I want to know what it was there for in the first place.
Cheers
Parent
Re:The comment may also be complex.. (Score:4, Interesting)
I've always subscribed to the theory that the code explains WHAT a program should do clearly enough that even a computer understands it.
Comments should fill in the gaps and answer the questions of WHY and HOW. For example, if I'm using a common pattern or idiom, I like to highlight that. I like to use the Delegation Pattern when doing SAX parsing of XML in Java. Rather that explain what the Delegation Pattern is about, I'll just cite the pattern name, add a link, and explain the nuances of that particular implementation and move on.
Parent
Re:The comment may also be complex.. (Score:5, Insightful)
Comments, for me, serve as a design tool as much as an aid to understanding. You can very quickly understand what my programs are supposed to do by reading the comments; not because my code is hard to understand, but because the comments describe its function as a narrative.
Of course, if you can't understand what the code does without reading the comments, you're doing something wrong. Once coded, the comments exist to extend and clarify what the code is doing, as well as adding meta data about how things like numerical constants were calculated.
Parent
Re:The comment may also be complex.. (Score:5, Funny)
For example:
Parent
Re:The comment may also be complex.. (Score:4, Funny)
I went on a vodka bender last night, and this was on my screen when I woke up.
I've had that happen to me a few times. It's a bit unsettling, I assure you.
What's even more unsettling is waking up with a full plate of hash browns and eggs next to my bed, and having no recollection of ever making them. It did make for a nice breakfast, though. Perhaps I should do it more often.
Parent
Or a management failure (Score:4, Interesting)
Or it could be just an indication of a management failure.
A couple of years ago I was brought in to save a project that was hopelessly behind schedule and getting nowhere. Pretty quickly I got the idea that whenever I check something into CVS, it gets re-checked by a really helpful girl there, richly decorated with comments. (Now I do comment classes and methods extensively, as well as places where higher elven magic was used, but I do _not_ write stuff like that now I'm iterating through a node's children. If you need a comment to understand that "for" loop, then there's something deeper wrong with my code.)
But, anyway, stuff like a line that said "if (currentNode.isRootNode())" had been decorated with the obviously helpful comment "// when the current node is the root node". I'm still at a loss as to what extra info is conveyed by that comment, since just reading the code out loud gets you almost the same sentence and definitely the same meaning.
And it went like that for every single line. Every single assignment, trivial loop, etc, was dutifully duplicated in that line's comment.
Turns out, they were asked to comment their code extensively, and judged basically by quantity. So she was just abiding by the rules.
Parent
Re:Real Programmers... (Score:5, Funny)
but Ugly goes straight to the code.
Parent
Re:Real Programmers... (Score:5, Funny)
Your code should be a narrative. How about
checkParamaters(...);
setupConnection(...);
submitQueries(...);
checkReturnValues(...);
The problem with this idea is that the actors in play don't lend themselves to a very compelling narrative. I mean, suppose I've got a data line that I've previously pulled low, and now I'm allowing it to float high - but I want to make sure it's actually floated high so I can be sure there's not somebody else pulling it low...
What is the data line's motivation for floating high? Apart from a current-driver driving the line high, I mean... Will the reader actually be able to relate to this conflict between two different slaves trying to assert different states on the data line? And, if we do make a narrative about this conflict, won't we have to explore the individual slaves' motivations for the conflict? Won't we need some depth of background information about the source of the address collision? Wouldn't the narrative demand proper explanation of the first slave's feelings upon learning he's lost arbitration, and condemned to forever remain in the shadow of the second slave? And what about the narrative of the second slave, who doesn't even know there was a conflict, because he's won it? These don't sound like very appealing characters to me...
Parent
Comments are good (Score:5, Insightful)
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. :-)
Re:Comments are good (Score:5, Insightful)
1) the code shall be simple and the name of variables and methods shall be self explanatory in most cases. When this is applied, there remains very few to explain at the code level. The reader of your code is not dumber than you (except when he is your boss).
2) the more you add comment lines, the less lines of code you can see on your screen. When you start scrolling continously, the speed of code production reduces significantly.
3) comments introduce a redundancy. What shall be trusted when code and comment differs. Is the code wrong or the comment outdated ?
4) comments in the code are often used as a substitute for a global software architecture description. In the example of the java api documentation, it is very hard to get a global view of a class with only class comments, we need additional documentation (the tutorials).
Joke apart, code often contains many comments because it shall comply to quality standards, but strangely, the parts of the code that are difficult to understand are generally not commented. It is a variant of Murphy law that is very useful when auditing code.
Parent
Re:Comments are good (Score:5, Insightful)
the first thing I do is delete the comments. I don't care what this person *THINKS* the code does, I only care what the code REALLY does.
*rolls eyes*
I, on the other hand, think it would be valuable to know if and when the person writing the original code *THINKS* the code does something which, in fact, it does not.
Parent
Co-workers (Score:5, Insightful)
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.
Re:Co-workers (Score:5, Insightful)
Or he's being a good employee and doing the right thing to ensure:
1. One to three years from now when the code needs to be revisited by him that he can quickly assess the code without thinking about it too much.
2. Long after he's gone another employee can come across the code and easily understand what was done and why.
3. Comments, to me, are like writing out all the steps in a math problem. Just because you arrived at the correct answer on the face of things does not mean that you understood what you did. Documentation proves, in many cases, that you did in fact know what the fuck you were doing.
--
If you don't like comments, fold them out of the way and be done with it. I just don't see the problem here.
Parent
Re:Co-workers (Score:5, Funny)
Parent
Re:Co-workers (Score:4, Funny)
Did you by any chance write ALSA? And did you write your long deceitfull unrelated comments in an APIDOX compatible format which later got published as a sort of documentation?
Because that.. would explain so much...
Parent
comments explain what isn't there (Score:4, Insightful)
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.
bad spelling in variables/etc get me (Score:4, Insightful)
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.
Re:bad spelling in variables/etc get me (Score:5, Informative)
I refer you to... the infamous "HTTP_REFERER".
Parent
Seems reasonable (Score:5, Interesting)
// teh code is obvius (Score:5, Funny)
Comments are for wimps.
Long-winded comments can be very useful (Score:5, Insightful)
Re:Long-winded comments can be very useful (Score:4, Interesting)
Often better than including the full explanation inline is: "Proof that this works can be found ...". Yes, it's one more reference to look up, but some of the algorithms in, say, Knuth, are long and complex proofs that really will interrupt your code reading if included inline.
A lot of good comments answer one of these questions:
- Why couldn't this be simplified?
- What special case is this trying to handle?
- This looks weird. Why is it right?
- What expectations are we demanding from elsewhere in the code?
A situation where I find myself asking any of those questions and no comment is present can be nightmarish.
Parent
Well, duh. (Score:5, Funny)
That's also why I don't comment my code.
Non-native English speakers (Score:5, Insightful)
English is not most people's first language. Be glad they want to write comments in English at all.
I'm an expert! (Score:5, Funny)
That's right, I'm an expert and I keep my code comments short and sweet. Observe:
function kick_ass()
{
while(true)
{
I agree, with reservations (Score:5, Interesting)
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.
Existence of Comments (Score:4, Funny)
(Any good Perl programmer knows this.)
You are not expected to understand this (Score:5, Funny)
The granddaddy of WTF comments must come from the original Unix source, written by none other than Dennis Ritchie: /*
* If the new process paused because it was
* swapped out, set the stack level to the last call
* to savu(u_ssav). This means that the return
* which is executed immediately after the call to aretu
* actually returns from the last routine which did
* the savu.
*
* You are not expected to understand this.
*/
if(rp->p_flag&SSWAP) {
rp->p_flag =& ~SSWAP;
aretu(u.u_ssav);
}
So here's an example of a comment that does an excellent (I assume) job of explaining why the code is doing what it's doing, yet the whole thing is so complicated that Ritchie even needed to acknowledge that the comment probably wasn't going to be of much help either with an amusing, and now somewhat famous, statement.
OT on long comments (Score:5, Interesting)
To maintain some sense of topicality: I don't particularly agree with the blog post. As someone with good English skills, I've read a lot of code where the English language skills (and thus spelling and grammar in the comments) of the coder are below mine, but their skills in the computer language at issue are superior to mine. Frankly, there's a far greater relationship between accuracy of the comments (do they actually describe what the code does) and the quality of the code, than there is between spelling, subject-verb agreement, and number of spaces after a period and the quality of the code. This relationship does follow the blog author's contention about coders needing to be nit-pickers.
Occasionally in my coding, I write a novel in the function header. Generally, this isn't because I don't understand the problem so much as its because I do understand the problem. I've spent hours or days understanding the problem, and the particular necessray function that implements the solution, and I don't relish spending hours or days 6 months in the future remembering what I know today. The interesting thing is that, most of the time, the novel is multiple times larger than the function - 50 lines of comment for a 20 NCLOC function isn't unheard of.
In my specialty (embedded systems, with especially tight hardware integration), there are functions that need to be written that deal with extraordinarily complex situations. Many times, the bare code tells a misleadingly simple tale - "do this, that, and the other thing", rather than (as Russ Nelson pointed out above)
but to explain all the other code that could have been written, but wasn't
. Oftentimes, the novel is there to explain all the ways to trip up in this 20-line function - e.g. unspecified hardware dependencies, subtle system dependencies, unobvious race conditions. Sometimes its there to explain why, no matter how wrong the function appears, it is actually correct.
syntactic and logical perfection can be crap (Score:5, Insightful)
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.
Re:10 PRIN "WTF" (Score:4, Funny)
Yes, yes they are.
when the code fails to run or runs is an unexpected way, while the bad comments won't stop the code from working, only from being understood.
It took a bit, but your comment is understood.
Parent