Code Tells You How, Comments Tell You Why

In an earlier post on the philosophy of code comments, I noted that the best kind of comments are the ones you don't need. Allow me to clarify that point. You should first strive to make your code as simple as possible to understand without relying on comments as a crutch. Only at the point where the code cannot be made easier to understand should you begin to add comments.


This is a companion discussion topic for the original blog entry at: http://www.codinghorror.com/blog/2006/12/code-tells-you-how-comments-tell-you-why.html
1 Like

Thank you for your blog–i read it almost every day and find it informative and interesting.

Sometimes when i’m writing code, i think “i should comment” this–only to realize that the comment is needed because it’s not clear how it works.

comments i gravitate to now are those that say “why” or indicate the intent of the code.

I always ask myself, “What questions would be asked by someone looking at this code for the first time?” And then I write comments to answer those questions.

Sometimes when I’m writing code, I think “I should comment this”

Right. The first and proper response to that feeling is to roll up your sleeves and refactor the code. After you’ve refactored, if you still feel a comment is necessary, then by all means add one. Never comment before you’ve attempted to refactor away the comment first.

I couldn’t agree more. Like the man says, if the code needs comments to explain what it’s doing, it isn’t done yet.

Two points:

  1. You are absolutely right - comments should describe the thinking behind the code, not the code. Especially important are decisions that were tried and failed.

  2. Your example of a good comment sucks. :slight_smile: It’s describing the code, not the thinking behind it. If you need context for the reverse string operation, why not write a “reverse” method?

A better comment might be “Reverse the string as a weak obfuscation technique” (for example)

1 Like

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.