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.'"
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 all this should have a reason, we would be the last to know.
Comments are for wimps.
"No matter where you go, there you are." -- Buckaroo Banzai
That's also why I don't comment my code.
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...
I am TheRaven on Soylent News
I always write long comments that either have no relation to the surrounding code or tell outright lies about it.
I always try to comment my code, but then the compiler keeps telling me there's no code to compile.
"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.'"
// This function kicks ass.
...
// This following code is like Chuck Norris. It doesn't know how to fail.
...
That's right, I'm an expert and I keep my code comments short and sweet. Observe:
function kick_ass()
{
while(true)
{
Precisely. Comments about code that the developer himself doesn't understand, usually because he employed some nasty hack and he's not sure exactly why it worked, are usually short and contain the word "magic" in them.
/* Magic happens here*/
/* Black magic */
/* Some particularly dark black magic occurs here */
/* I'm not sure why this works, but it does */
/* I went on a vodka bender last night, and this was on my screen when I woke up. I don't know what it is, but it compiles, so let's ship the fucker. We'll call it Vista. */
For example:
If comments even exist, then the code is ugly. Code should document itself.
(Any good Perl programmer knows this.)
Adidas To Bring Back Sneakernet
Unless your code is running in IE5 or IE6. Then you get it to work by chance, and do not ever touch it again.
Go green: turn off your refrigerator.
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.
The only difference is that a lot of bugs are obvuous,
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.
We will bankrupt ourselves in the vain search for absolute security. -- Dwight D. Eisenhower
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.
Alexander Peter Kristopeit bought his basement from his mommy for one dollar.
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.
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.
Alexander Peter Kristopeit bought his basement from his mommy for one dollar.
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...
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 (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."
If you are responsible for the code, you are a fool if you let ANYBODY touch it.
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?
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.
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...
Alexander Peter Kristopeit bought his basement from his mommy for one dollar.
Yeah, I can't believe how badly they typo'd the word REEFER.
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.
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!
Beauty is only GUI-deep,
but Ugly goes straight to the code.
I prefer rogues to imbeciles because they sometimes take a rest.
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...
Bow-ties are cool.
Do not try to understand the "why" of IE6, that's impossible, simply try to realize the truth. There is no "why." Only then will you see that it is not IE6 that conforms but only your code
-- Adam McCormick
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.