James Britt wrote:
> Dave Fayram wrote:
> > Your code isn't the place to justify your position
> > post facto. The fact that the code works should be justification
> > enough. :)
>
> Yeah; I've written lots of code that, um worked.   It just  worked at

> the wrong thing.

So documentation would solve this problem? I don't think so. Unit tests
solve this problem to the extent that any modern solution can.
Documentation is just as likely to lead you astray as help you here.

> I don't see how one goes from writing comments to having a
> documentation-heavy approach.  Or how it equates to up-front design.

In your next statement you claim you should write the documentation for
a method first, then "convert" it to code. I maintain that this is
"design-up-front". I've had plenty of scenarios where I think I know
exactly what I'm about to code, and then in the process of coding it I
realize that I had it all wrong, overlooked something, etc.

And please observe, I am not against writing comments. In all the code
I write, I'm usually the first to document my signatures and I prefer
to put examples in wherever I can find an excuse.

> But a better approach might be to write the method comment first,
then
> convert the comment to code, such that the comment is no longer
needed.
>   And if you find that you cannot do this, then that may be a code
smell.

Maybe it is a smell, but it's the good kind that lets you steer your
code based on what it needs to be, not what you think it ought to be.
See the comment above.

I think what you're describing is not only a headache, but inefficient.
If applicable, I'm already writing unit tests. When I'm convinced that
I haven't made a misstep, I'll document it.

Documenting untested code (as in, explaining in english an algorithm or
procedure which has yet to be tested, which is a necessity of your
approach as described above) is a waste of time and effort. If you're
wrong, you now have that much more information to change.

> I believe that developers can forget that what seems obvious at the
time
> the code is written will often seem cryptic later on, ever to the one

> who wrote it.  Writing it down forces you to at least make the point
> explicit, and help the coder see if he or she has a clear
understanding
> of what code is supposed to do.

I believe this is a reaction to poor coding practice, and not a
necessity. I've picked up code that I wrote years ago and managed to
step in with only minor headache. I don't think I'm special, or have
any super-brain-abilities that let me do this. I just happened to work
with someone who made me code with good style and document
appropriately. There was nothing special about it (unless you deem a
college research product being maintainable as special, which it may
be).

Oh, and we had a readme explaining what the code did at a higher level
(*cough*techmemos*cough*).

> I find the a best way to know if I understand something is to try to
> write about it.  It forces me think in a certain way that talking or
> coding does not.

Funny, I find the best way to understand it is to *do* it and *test* it
and *try* it. Then, if it seems right and holds water, I keep it. If
not, then I made a mistake and obviously I need to recode it.

For me, unit tests as test first serve the function you are describing.


> That's great when it happens.  But there is too much core ruby rdoc
that
> simply gives an obtuse method and a set of terse variable names. Not
a
> word on what the method does.

No fair making a point that I agree with, and spinning it like I don't.


I'm not arguing that documentation is useless. I'm arguing that the
essay mentioned above goes too far, and that Literate Programming is
something I find pointless and inefficient (with all respect to Mr.
Knuth of course. For the kind of work he does, it probably makes a ton
of sense).

> Not everyone agrees with that.  I'm past the "Where do I start" step
and
> routinely have problems understanding how to do what should be simple

> tasks.

It's a logically untenable to say what I'm about to say, but I'm going
to say it. If you're still having lots of fits and false starts in
Rails, it is probably because you're not past that awkward first step.

But that aside, are you claiming that Rails needs more documentation?
:) It's allready one of the most well-documented projects anyone could
ask for. And while some people may not agree with it, it's undeniable
that many Ruby Nubys have come in and made meaningful patches to the
code. If that's not evidence of maintainability, I'm not sure what is.