If the Comments Are Ugly, the Code Is Ugly 660
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.'"
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!
Re: (Score:3, Insightful)
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 ...
Re: (Score:3, Insightful)
I think you are following a "false" (i.e. unlikely enough to be a bit absurd) argument here.
And hats off to the coder with humanity enough to make other coders' jobs easier if things should get to the point of having to fix said code: at least we know where to look first.
First they came for the project managers...
Re: (Score:2, 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? Could it be optimized? Sure...
Those that seek perfection are destined to a life of search. Those that seek 'working' are destined to a life of success...
Re: (Score:3, Insightful)
That's true with anything, though. There often comes a point at which further improvements just aren't worth the effort, no matter what product you're working with. With rare exception, where tolerances in engineering are extremely slim, your work only needs to fall within the tolerances of the person you're working for.
Now, if you're a good coder, and your code is already pretty 'perfect', that's great. Many programs benefit from optimization even if they worked satisfactorily to begin with, too. Don't exp
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.
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.
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.
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*.
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.
Re: (Score:3, Funny)
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.
Re: (Score:3, Informative)
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)?
ROFL, because I'm a moron, that's why. Honestly, is that so hard to understand?
if you are coding in microsoft land (Score:3, Insightful)
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
Re: (Score:3, Insightful)
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
Ah, external dependencies are a very different thing, though.
If I'm coding against an external library, and it behaves unexpectedly, there's little I can do but to document the issue, explain that the code is written to work around a mysterious library bug, and move o
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?
Re: (Score:3, Informative)
You've obviously never actually built a real world building. You'd be damned surprised at how inexact so many things are. Something may measure 12 feet on the plans, you may take a 12 foot board to place and when you get there, you'll still cut it to fit or hammer it into place. Construction, even of your vaunted bridges is filled with hacks carried out at all levels of the build.
Software development typically isn't engineering. It's usually a business of maximizing productive features versus minimizing
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.
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.
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.
Re:The comment may also be complex.. (Score:4, Informative)
Also known as survivorship bias [wikipedia.org].
Re: (Score:3, Insightful)
There's a huge difference between 16 inches on center being more like 15 to 17 in practice and having no idea why the building won't fall down. As long as the engineer KNOWS for a fact that the building will be fine at 18 inches OC, it's not a problem. He can only know that for a fact if he knows how the load distributes and how strong the materials are. He doesn't get to just have it slapped together any old way and then try it differently if it falls.
The various hacks in building are just compensations f
Blame Game (Score:3, Insightful)
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 an
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".
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.
You've got it backwards. (Score:3, Insightful)
"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:
Re:The comment may also be complex.. (Score:4, Funny)
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).
boss? is that you?
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.
Re:The comment may also be complex.. (Score:5, Insightful)
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.
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.
Re: (Score:3, Informative)
As a programming "old coot", I'd say that if you didn't understand why, then yes, by definition that's bad coding. You need to understand the problem before you can fully address the problem. And if the solution is complex, your comment shouldn't say, "Wow! I can't believe this worked. Good luck if you need to change it!" It should instead educate those that come behind you. Comments should be an aid to understand not only the code but the problem domain addressed by the code. It's a means of recordi
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
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.
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.
Re: (Score:3, Interesting)
True. Furthermore, it's arguably proper, when implementing a particularly clever and streamlined hack (i.e. impossible to decipher, when debugging the code), to set it off from the code visually and then follow it with a commented-out block of code which does exactly the same thing, albeit slower or less efficiently, and which will be much easier to understand.
As a bonus, if the code must later be changed and the original hack would no longer be possible in the new functionality of the code, the procedure h
Re:The comment may also be complex.. (Score:4, Interesting)
I've gotten into the habit of commenting first, coding second. It is especially useful in complex systems.
I find that if I write the high level logic in comments of all the functions I'm going to write, it helps me find where I should break out repeated logic and solidifies the design. Once everything has been commented, I can go back and write the code.
This lets me know what the variables are going to be and can name them appropriately (why name it `i` when I can call is `block_index`). I don't lose the big picture of what needs to get done. It gives me targets to meet and stopping points at the end of the day (a sense of accomplishment and goals for tomorrow is *really* nice). Future coders can read my comments and see what I was thinking (this has actually happened to me). As a bonus, I can worry more about corner cases as I'm writing the code instead of creating corner cases to worry about later.
I've done it with a Flash memory interface, O/S memory manager, and a kernel module. Each time I've finished, even if it isn't the best code in the world, I know that if the next person reads the comments, they'll know what I was thinking.
Better code all around.
Re:The comment may also be complex.. (Score:5, Funny)
For example:
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.
Re: (Score:3, Funny)
We ran across a classic one of these. A application we developed in 1992 stopped working in 1994 for some unknown reason. After a few days of heinous debugging to build a test case, we come across a line of code headed with this comment: /* this will not work - jr */
We fix that line so it will work, and all have a good laugh later. At the time it was pretty frustrating as I recall. I'm still good friends with JR by the way.
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.
Re:Real Programmers... (Score:5, Funny)
but Ugly goes straight to the code.
Re: (Score:3, Interesting)
I don't fully agree... however, I do think its sometimes true.
Often, one of the ways I know that my code is pretty good and well organized is that I find few places ... // setup the connection... // submit queries ... // check return values"
where comments would even be helpful. Often the comments just end up deliniating sections so I can skip to them easily "// check parameters
Of course, are we counting the comments that document what a function does? As I have been mostly playing with Java lately, the java
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...
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.
Re: (Score:3, 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.
4. Cross-referencing the specification, for reverse traceability.
Of course for those of us who code perfectly the first time, they aren't really needed. :-)
Requirements never change, do they?
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.
Re: (Score:3, Funny)
Of course the person who wrote the code *THINKS* the code does something which, in fact, it does not
Sure, but it's helpful if they tell you what they think it does, in detail. If you're lucky, you can ask them and they might remember. Or they could just write it down once somewhere convenient. Perhaps it might be stored along with the code.
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.
Re:Co-workers (Score:5, Funny)
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...
Re: (Score:2)
Re: (Score:3, Interesting)
One of the things I prefer doing, in fact, is to write out a series of "steps" that I intend to do in comment form, one per line (perhaps multi-li
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: (Score:2)
Comment removed (Score:5, Informative)
Re: (Score:3, Informative)
America isn't the only country in the world. In England and Canada, "honour" is the correct spelling and "honor" is the "alternative" spelling.
--- Mr. DOS
Seems reasonable (Score:5, Interesting)
// teh code is obvius (Score:5, Funny)
Comments are for wimps.
Re: (Score:3, Funny)
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.
Re: (Score:3, Insightful)
Linked stuff has an annoying tendency to not be available when you most need it, be it expired domain names, dying servers or even reading the comment in a WiFi-less coffe shop. Cited books tend to only be available in a different edition than referenced.
But the solution's quite simple: GP, keep on commenting as long as necessary. IDEs and even rather simple editors have allowed coders to collapse comment blocks for several generations now. Long comments are no problem.
Well, duh. (Score:5, Funny)
That's also why I don't comment my code.
Re: (Score:3, Informative)
That is not the fault of the practice of commenting code. That is the fault of lazy-assed developers who don't maintain the comments.
That's like saying engineering is rigorous because
Re: (Score:3, Insightful)
>> 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 in
Sounds right (Score:3, Funny)
It should be obvious what the code is doing just from reading it. If it isn't, then the code should usually be refactored. Comments are for explaining why the code is doing that. If your grammar is poor in the English then it's probably poor in the code too (unless you are not a native speaker). If you make spelling errors in comments then you probably do in code too. The compiler will catch some of these, but when you accidentally type the name of an instance variable or a global instead of a local, it won't spot it. If you're not checking your comments for this kind of error, you're probably not checking your code for it either.
Just as with online comments, poor grammar displays a lack of care. Hopefully, more people will be reading your comments than will be writing them. A little effort in writing them can save a lot of effort in reading them. If someone on the Internet thinks that their time is worth so much more than their readers' time then that just makes them an asshat[1]. If a programmer thinks his or her time is so much more valuable than that of people maintaining the code then he or she is a terrible programmer.
[1] I am fully aware of the universal law that means that, by writing this, my post will have a significantly above average number of typos. Please be nice...
10 PRIN "WTF" (Score:2)
This seems like a no-brainer to me. Sloppy people are sloppy and stupid people are stupid, how is this not evident? The only difference is that a lot of bugs are obvuous, 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.
There are a lot of times I'll see slashdot comments like "you might loose your mind" and I think "I hope that guy's not a programmer." Loosing your mind is quite a different thing than losing it, and
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.
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.
Bad spelling too often = bad thinking (Score:2)
Or at least sloppy thinking. I have no idea why this is, but as anyone who has looked at internet blogs can attest, the people who can't be bothered with proper spelling, grammar, punctuation or capitalization, or who can't differentiate between "loose" and "lose" are also (usually) the biggest idiots.
Not always true (Score:2)
Doesn't work (Score:3, Funny)
I always try to comment my code, but then the compiler keeps telling me there's no code to compile.
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)
{
Re:I'm an expert! (Score:4, Funny)
You forgot ass_needs_kicked = true and while(ass_needs_kicked).
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.)
Forced to use Bad API (Score:3, Insightful)
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.
An addition (Score:3, Informative)
Dennis Ritchie has a whole page of comments [bell-labs.com] in the Unix source code, and what information they convey.
Re: (Score:3, Insightful)
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 g
Re: (Score:3, Informative)
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.
Sorry but that is just a piss poor comment and there is no excuse for glorifying it. If it's that complex, he needs to refer back to a particular section of a particular version of a design do
Re: (Score:3)
I hope I never work with or have to deal with code from whoever thought that was flamebait.
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.
Tästä voit hakea sanan kategorian (avain (Score:3, Funny)
I cut text from Finnish language websites and paste it in as comments. I don't know what it says, but it looks really cool.
Author is a Drama Queen (Score:3, Insightful)
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.
Comments are for future maintainers (Score:4, Interesting)
I feel that comments can be broken into four types:
Coding Drunk (Score:3, Interesting)
Re: (Score:3, Interesting)
Such a cool teacher... and the Computer Science head now...
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.
The reality... (Score:3, Interesting)
I tend to write comments of varying lengths - sometimes, writing longer comments not for my own benefit, but for the benefit of the next coder - someone who may or may not have my understanding of the system or code; and more likely than not, either won't have the time to learn the code 100% in-and-out, or are not up to the same par. So sometimes, I will write a large comment block on an important thing in the code - so that they (whoever they are) will be able to understand it quite quickly. However, that is (as it should be) quite few and far between; sometimes documenting complex logic from elsewhere in the system that I have no control over but the programmer needs to be able to understand.
Of course, there is also the typical PHB managers who evaluate their programmers based on LOC, SLOC, and CLOC (LOC = SLOC + CLOC), and look for an even distribution of SLOC/CLOC - e.g. SLOC/CLOC = 1. In some cases that is good; but in most it is not.
All in all, you can't tell how good the program is by just general comments or comment analysis.
BUT if you are sloppy in your comments (grammar, spelling, etc.), you have probably been sloppy in your code. To that end, I do very well agree with the article.
P.S. BTW, I've been in 3 positions where I have replaced people. One fired; one died; and one quit. In two of those three, the original developer was no longer available for inquiry; in the third, it was possible but not easy and only for a short time after he left.
Comment bugs and lack of comments a worse problem (Score:3, Insightful)
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.
I can't believe the OP is even possible (Score:3, Insightful)
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.
Re: (Score:2)
/* What you mean, my comments not good? My comments very good! You very bad man! */
Re:Nonesense (Score:4, Funny)
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.
You. Are. Doing. It. Wrong.
If the code evolves, fix the comments. Unless you're deliberately trying to confuse the next person who gets the pleasure of maintaining your code...