Comments On Code Comments?

theodp writes "It seems like comments are on programmers' minds these days. The problem with comments, as Zachary Voase sees it, is that our editors display comments in such a way as to be ignored by the programmer. And over at Scripting News, Dave Winer shares some comments on comments, noting how outlining features allow programmers to see and hide comments as desired. 'The important thing is that with elision (expand/collapse),' explains Winer, 'comments don't take up visual space so there's no penalty for fully explaining the work. Without this ability there's an impossible tradeoff between comments and the clarity of comment-free code.' Winer also makes the case for providing links in his code to external 'worknotes.' So, what are your thoughts on useful commenting practices or features, either implemented or on your wishlist?"

Comments

Doesn't matter in the end

[crazyjj]

Changing the color of the comments, or making them collapsible/non-collapsible isn't going to have any meaningful impact. A rushed or sloppy coder is going to ignore them either way. And a conscientious coder is going to read them regardless.

The real problem with comments isn't their color, it's when they AREN'T THERE AT ALL. You could have the damn things flashing in rainbow colors and it still wouldn't change the fact that the legacy code I'm going over was done by a sloppy piece of shit who never wrote any comments in the first place, or who wrote cryptic/indecipherable comments that would take a linguist 10 years to translate into meaningful English.

Now, if you'll excuse me, I've got to go play Sherlock Holmes with some strange method written by an Indian contractor whose only comment on it was "This move thing around."

Re:Doesn't matter in the end

[garcia]

The real problem with comments isn't their color, it's when they AREN'T THERE AT ALL.

THIS. I deal with sloppy coding convention all the time but at least when the code is commented I can get a mile-high view of what each section is doing w/o having to spend time carefully piecing the work apart to figure out what happened.

The lack of comments for others is annoying but I really want to know how people go back into their own code several weeks (or even days) later and know what the hell they did when there are no comments.

Many times I have run across a commented section of code that reads something like:

/* Attention future Bill: this section of code sucks and it looks horrendous and awful but I wrote it under a tight deadline. Just hit F3 and let the bitch run; it works, I promise. */

I can only shake my head at myself ;-)

Re:Doesn't matter in the end

[crazyjj]

/* Attention future Bill: this section of code sucks and it looks horrendous and awful but I wrote it under a tight deadline. Just hit F3 and let the bitch run; it works, I promise. */

Makes you want to kill Bill, doesn't it?

We need STRUCTURE

[For a Free Internet]

In order to better utilize synergies and business genius patterns of excellence, comments need to be stored as XML in a cloud-based LDAP database that partners, stakeholders, clients and yourmom can access via an iPhone app. If you don't do this you are a monkey, or maybe a horsepig.

Re:Contrast

[crazyjj]

Could be worse. They could use white on white.

You're missing the point

[For a Free Internet]

Hey asshole, I don't know about you, but I make my comments on Slashdort , where they are appreciated and honored by the Slashdort community, whereas you are a noxious pigfart sniffer and dogsmoocher.

Don't mind me

[Sez Zero]

I'm just here for the Comments on Comments on Code Comments.

Re:Removing comments from code

[RobertLTux]

in the case of some inglorius hacks documenting WHAT YOU WERE DRINKING at the time may be the most useful (or what you were on or the fact that you were on hour 47 of your shift...)

TFA sucks

[Sloppy]

As soon as I saw that the guy wrote "UX" I knew I was probably dealing with an exceptional moron (how that one acronym has turned into such a reliable red flag, I don't know, but look around and try to tell me it isn't true), but I still had no idea just how badly the article would go. It's not even stupid. It's just .. nothing.

The guy's argument is really that his text editor's preferences are/were set to something he doesn't like.

I shit you not. His editor's preferences were something he considers to be not-quite-right, and he noticed that it wasn't working well for him, and then somehow that turned into a programming article.

I can't even follow through on my "UX" prejudice and say "Aha! See? The guy knows nothing!" because he's taking it to the next level, so that from now on when I see "UX" it'll be "Aha, See? The guy says nothing." Although now that I think of it, maybe that's what the "UX" red flag has really always meant, all along. Hmm. Ok, you did give me something to think about.

Re:My views

[Animats]

Transfer this guy to maintenance programing for a year.

Re:All comments are lies.

[rastos1]

When I write comments it is usually to say "this code might look like an opportunity for this or that refactoring/optimisation. Don't do it becauase..."

You mean something like this:

//
// Dear maintainer:
//
// Once you are done trying to 'optimize' this routine,
// and have realized what a terrible mistake that was,
// please increment the following counter as a warning
// to the next guy:
//
// total_hours_wasted_here = 42
//

?