Re: Comments Are More Important Than Code

James Britt wrote:
> Maybe.  Certainly, running code is no proof
> of anything other than that the code runs.

Which is more proof than anything documentation an ever give you. I can
provide a pile of documentation for you. It proves exactly nothing. It
does exactly nothing. Without code, the documentation is worse than
worthless.

Which is not to say that it's worthless when coupled with code.

> Writing out the intent and goal of some class or method
> before writing the code may help the developer clarify
> his or her thoughts, such that the code may be more likely
> to be written correctly.

So can unit testing. And unit testing is repeatable. And it lets you
know when it's no longer correct, because the test will break.

> In the end, you have to have a clear understanding of what the code
> should be doing.  Comments can help.

I never said comments were bad. Please stop trying to force me to
maintain a position I never intented (nor intend) to take. I'm all for
documenting and commenting your code.

I feel that the extremist approaches, as given in that article, are
steps backwards and not forwards. Did you read the article? Did your
realize what he was really suggesting?

> Interesting.   This sound like, "Just code, don't design at all."

No. It's not. The fact that you think it is is telling to me. It's a
common extreme programming idiom to start coding and getting into
iterations quickly. I have no inclination to redundantly spout its
justifications when a perfectly good piece of literature exists on the
subject.

Part of the algile methodology is to cut down on extraneous products so
as to help prevent that exponential-cost curve that we see so often
when being told the benefits of the Waterfall Method.

> If first I write
> # This should check that a given user name does not exceed
> # a max length because of reason foo
>
> and that convert that to code, have I done "up-front" design?
>
> Perhaps.

I'd much prefer to see (this is pseudo and formatted for short lines,
so bear with me):

  def my_appropriately_named_test
    long_name = "This name is far too long."
    assert_raise Module::InputValidationError,
                 @inst.the_func( long_name )
  end

Then I can test it. If I ever make a change and accidently invalidate
it, then I'll know. If we ever eliminate that restriction, the test
will break and we'll know to update it.

> Would creating CRC cards be up-front design?
> Would that make them bad?

CRC cards do not exist at this level. They are extremely high level
abstractions and once the code is written, you can throw them away.
They are not expected to be more than a way of capturing your rough
thoughts about the project.

Please, stop trying to pigeonhole me into a position I didn't take.


> I prefer to decide what the code does,  not let the code decide for
> itself.  Comments-before-coding are similar to sketching in a drawing
on
> canvas before doing a large painting.  No doubt, as a work develops,
> things will have to change, but that doesn't argue for the
elimination
> of the entire sketch.

I'm not going to argue that your way of being productive is bad. I am
going to argue that making the default entry mode in a file of source
code the comment mode is crazy.

I'm not going to argue that a little bit of sketching and writing and
even commenting up front is a bad thing, because I don't believe that.
I do believe that excessive use of this technique will lead to
inaccurate comments and possibly lead people to believe they don't need
unit tests.

> Same goes for writing unit tests that test the wrong behavior.  I see

> comments as a way of helping ensure the developer is clear on the end
goal.

I find them to be troublesome. But as long as we aren't seeing
excessive amounts of comments, aren't substituting them for good unit
tests, and not using them as an excuse to get away with bad code, then
I'm fine with them.

I just believe that they are, and forever will be, secondary to good
code and good unit tests.

> > Oh, and we had a readme explaining what the code did at a higher
level
> > (*cough*techmemos*cough*).
>
> Does that doc lie?  Was it written to define the intent of the
program
> prior to coding, or written to explain whatever the code ended up
doing
> after development?

It was written to explain the state of the document at release time.
This happened 3 times during the life of the software. We also kept a
CHANGELOG and TODO file. So it's far more likely to be accurate, since
we had the code up front and then wrote about it. Sure, it's a bit of a
hassle to maintain a good readme file, but obviously it's important and
helpful to do so.

> That's too funny.   Blame the user.  This is the sort of thing that
> makes Rails-rooters so endearing.

Grow up. I'm not blaming you. I'm suggesting that there is yet more to
learn  to achieve comfort with the framework. Sheesh.