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.'"
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!
// teh code is obvius (Score:5, Funny)
Comments are for wimps.
Well, duh. (Score:5, Funny)
That's also why I don't comment my code.
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...
Re:Co-workers (Score:5, Funny)
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:The comment may also be complex.. (Score:5, Funny)
For example:
Existence of Comments (Score:4, Funny)
(Any good Perl programmer knows this.)
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:// teh code is obvius (Score:3, Funny)
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.
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.
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.
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.
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: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...
Bill Watterson put it so eloquently (Score:2, Funny)
http://74.125.93.132/search?q=cache:6l-STbmY0DkJ:www.gocomics.com/calvinandhobbes/1993/07/28/+site:www.gocomics.com/calvinandhobbes/1993/07/28/&cd=1&hl=en&ct=clnk&gl=us [74.125.93.132] (sorry, Google cached copy because the website is weird)
CALVIN: "Dad, what's a control freak?"
DAD: "That's what lazy, slipshod, careless, cut-corner workers call anyone who cares enough to do something right."
CALVIN: "Am I in the presence of their king? Should I kneel?"
DAD: "If anything works in this world, it's because one of us took charge."
Re:The comment may also be complex.. (Score:1, Funny)
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: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.
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...
Re:bad spelling in variables/etc get me (Score:1, Funny)
Yeah, I can't believe how badly they typo'd the word REEFER.
Re:Comments are good (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.
Re:The comment may also be complex.. (Score:2, Funny)
Sir, your attitude is a breath a fresh air. Any programmer who doesn't submit a formal and rigorous proof of every algorithm they write to a peer reviewed academic research journal is an incompetent hack who couldn't program his way out of a cardboard box.
Programmers who pick and choose their development practices based on the specific requirements of the project at hand are ignorant fools who reduce the beautiful and perfect art of programming to a mere act of common labor. It's disgraceful, I tell you!
Re:I'm an expert! (Score:4, Funny)
You forgot ass_needs_kicked = true and while(ass_needs_kicked).
Re:Real Programmers... (Score:5, Funny)
but Ugly goes straight to the code.
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...
Re:The comment may also be complex.. (Score:3, Funny)
WTF comments (Score:1, Funny)
You should at least comment your code, such that the next time (3 am) someone (you) is looking at your code you can make some sense of it.