From: Dave Fayram <dfayram@...>
Date: 2005-04-29T00:39:33+09:00
Subject: Re: Comments Are More Important Than Code

Mark Smith wrote:
> I agree.  Steve McConnell in "Code Complete" illustrates the idea of
> writing pseudo-code of what the method (or routine) ought to do.
That
> is for a human code reader.  The art of writing code is translating
the
> pseudo-code into terms the computer can understand using correct
syntax
> for your chosen language.  When you're done, the pseudo-code can just
be
> converted to comments to document exactly what the code was supposed
to
> do (assuming the coder did not create a bug with incorrect syntax).
> ...
> I agree again.  After all, unit tests are themselves CODE--and are as

> susceptible to bugs as "actual" code.

Why is your pseudo code any less susceptible to bugs? I mean, compared
to C++, Ruby *is* pseudocode. But we can still have bugs in Ruby. If
you write code, and then another code representation, you're asking for
trouble. One of them is going to end up wrong. I think the reason for
this is twofold. One, while some bugs are typographic, the vast
majority of them are errors in our own though processes. Comments in
this fashion may help you express that thought and realize it, and may
even help you work out bugs. But, if you've already got an error in
your thought, nothing short of trying it out and being shown it's wrong

The second reason is that when making code maintainable, you have to
make sure to make it refactorable. This isn't optional anymore.
Maintainable code is refactorable code, proper subset, no escape. When
you're refactoring, are you going to refactor the comments as well?
Can't errors be introduced at this stage as well? How do you know if
your pesudocode comments are correct?

> Exactly!  After all, if a routine/method is supposed to increment any

> value by 10, a test that 25 becomes 35 is of no value if all the code

> does is return 35 no matter what is passed to it.  The code runs, but
it
> will fail to return correct results for every number other than 25!

Ah. But now we're talking about a bad unit test. A good unit test
asserts the edge cases and at least two common cases. And pseudocode
comments don't wave a magical correctness wand and make this problem go
away either. :)

> Of course, a comment like "Step through by twos" does NOTHING to help
a
> code reader understand that the loop is stepping by two's.  However,
a
> comment like "Apply this to the even pages in the report" explains to
a
> code reader WHY the loop is stepping by two's . . .

Well, I can see your case here for that, but I'm from the school of
thought that would make an each_even_page iterator and use that. I
mean, it's pretty hard to argue that this:

    # Apply this to the even pages in the report
    ep = treport.pages.reject { |page| page.number % 2 == 1 }
    ep.each { |x| some_operation( x ) }

is readable just because you have introduced the extra redundancy of a
comment to make it more readable. In true Smalltalk party-line, I'd
much rather see this:

    treport.even_pages.each { |page| some_operation(x) }

One has a comment, one is written in a more self-documenting style.
Now, of course, you could do both, but then you can sometimes almost
double your maintenance work. I'd say the comment would be redundant
with the code snippet above, and aren't we supposed to avoid repeating
ourselves? :)

In my experience maintaining code (and I've maintained some truly evil
code, please see the MEL BUFR library) the worst thing that can
possibly occur is when the comment lies. It says, "This code does
this." However, the code doesn't do that. It segfaults, or does
something else. Maybe this is a personal flaw of mine, but I give
enormous weight to the comments I read in code. They're like little
messages that the developer saw fit to leave me. So when they're wrong,
I am very agitated. I mean, I'm supposed to be able to trust them,
right?

So, to avoid doing that, I keep my documentation to my function
signatures except under extreme situations.