Code Tells You How, Comments Tell You Why

Eric Lippert had related posts on the same topic:

http://blogs.msdn.com/ericlippert/archive/2004/05/05/126739.aspx
http://blogs.msdn.com/ericlippert/archive/2004/05/04/125893.aspx

JD

As always, excellent. Right to the point and informative.
In favor of comments vs. no-comments, with the advances in IDE, most offer syntax highlighting these days.
Sometimes, while reading a sequence of black and blue (standard VS colors), having a a line of green in the middle makes it jump out.
The reverse goes of course… too much green kills the green.

I agree with Robert. If I have to write comments like “# Reverse the string” its going to end up with more comments than code. If a developer considers that to be opaque they’re better off not even trying …

Dave, as pointed out in the early part of the article, comments should be useful not primarily for the person who writes them, but for those who read them.
While the example given may not be so obvious for most Perl programmers (experience level?), it may not be that obvious to non-Perl savvy programmers.
And it is possible that some may, one day, want to convert that particular program to a different platform or language. In that particular case, it is very likely that the person who reads the comments (the intended audience of comments after all), is mostly interested in the “what?” and not the “how?”.
And from personal experience, my coding style does evolves, impacted by several factors, including platform evolution, language evolution, experience. If I look back, I may not write the same line(s) of code to do the same thing months or years later.

In general, the amount of comment needed for a line depends on its complexity.
int i = 0;
Does not need comments.
return new ObjectEl(Math.Max(arg1, arg2), RetrieveObect(arg3, DB_NAME))
probably would require a comment. Even better, as suggested in by Jeff and other poster, it could be re-written to be self explanatory.
Writing compact lines of code does not produce compact code or faster code… leave it up to the compiler. But I guess that’s a whole different article (Jeff :wink:

ugh. since when did writing code become intertwined in the eccentric world of art. Suggestion. If you’ve hired programmers that are too stupid to read either the comments or the code, you’re SOL. If I hired someone that wasted their valuable brain power on this nonesense we’d never get anything done, and I’d most likely fire the guy on the spot. Leave this eclectic crap to abstract spatter paintings and religious philosophical banter whilst sipping wine by the campfire.

Johnny, every line of code is read several times but written only once. Spending the time upfront to make it readable and understandable is a direct productivity gain.

If you need context for the reverse string operation, why not write a “reverse” method?

Touche.

Couldn’t agree more. I wrap a lot of “weird” code like this with well-named functions.

1 Like

I found the comment above interesting, having worked on projects where the attitude was “Don’t waste time on structure or commenting, do it at the end” and seeing code written that was good enough simply because it worked, I have found that you’re exactly right. Coming back to the code even weeks later it was incromprehensable, even with an understanding of what the intention of the programmer was. There’s nothing quite like seeing “int temp1 = …” to confuse the hell out of anyone trying to read what you’ve done.

I would suggest that Johnny reconsider his management style if that’s his approach; good code structure should be encouraged by management. It takes a little longer now, but in 1 or 2 years when the system breaks down and you need to get a guy in to fix it, you don’t want him to be wading through meaningless variable names and weird program structure just to fix a simple mistake.

As a side note, that Perl example makes an argument, but not the one the surrounding text implies. In fact, it might fit higher up in your post, because the correct way to reverse a string in Perl is vastly simpler:

$string = reverse $string;

The join and split operations were probably cargo-culted, and it was the very act of cargo culting that left an obfuscated mess that requires a comment.

Sometimes the best way to be clear when programming a particular language is to learn the idioms of that language well.

Of course, this is Perl, and “baby talk” is explicitely allowed – everyone has to start somewhere. :slight_smile:

I do wonder about this non-comment fetish.

When I was taking programming classes in college, we got hammered if our code was not commented. The idea was to have the how and the why in it, such that it was easy for the grader to skim through the code and tell if it was correct.

Of course, this had a lot of push back from the students who hated wasting time on it. But it did produce code that was understandable by novices.

I might have commented on this, but it seems superfluous.

Well…I hate to have to point this out, but the double use of ?: in that example just highlights a bad coding technique. How much clearer would it have been NOT to use the horror that is ?: ?

My guess is that should be:

reverse a string word-by-word

$string = join(’ ‘,reverse(split(’ ',$string)));

Ha, perhaps we were both screwed by your blog software - those should be quote space quote
not quote quote.

Ha, I (and maybe you) got scrwed by your blog-software eating our spaces. Those should be quote-space-quote not quote-quote.

One use for comments raised in a code review:
searchable string for maintainance. We’re all familiar with //FIXME, but how about

//Defect v4.04#112: customer wishes amounts above
//MAXAMOUNT reduced to max and processed

to identify where and why but not how
if( amt MAXAMOUNT ) amt = MAXAMOUNT;

I accepted this suggestion to improve maintainance; your comments?(I know, all CAPS is EVIL, but…)

Martin Fowler makes the observation that code comments, while not strictly a code smell, can be used as a deodorant for code smells. Frequently, they’re an indication that something needs refactoring. It’s not that they are bad, but lots of times they are used to account for poorly factored code.

Said better, while not ignoring this is still very much an issue of preference: http://c2.com/ppr/wiki/WikiPagesAboutRefactoring/CommentCostsAndBenefits.html

$reversedString = blah blah blah

is IMO better, and more concise

Good point. I use comments as notes to myself as much as notes to others. It’s not just the ‘why’, but also what I’m thinking at the time. That way, when I have time to refactor that portion, it’s a bit easier. I hate looking at code I’ve written and thinking, “What the hell was I thinking?”

"$string = join(’’,reverse(split(’’,$string)));

reverses your string, but how hard is it to insert

Reverse the string "

Well, thank goodness. At least you are ok with some comments on “what the code does”.

This has become such a dogmatic thing these days…just like so many other decent ideas, they are horrific when taken too far.

I certainly don’t mind a comment telling me what it was supposed to do, as well as how. Can make it easier to debug if it breaks later. At least you know what the intent was, and you can see if it matches.