[Novalug] documentation

[Kevin Cole]

On Thu, Apr 17, 2008 at 7:36 PM, Chris Flipse <flip at csh.rit.edu> wrote:
> On Thu, Apr 17, 2008 at 06:32:12PM -0400, Ed James wrote:

> > I agree, with a small twist.  Long ago, I started doing the
> > comments first, to make sure I understood what I wanted to do,
> > and to make sure the logic was sound.  This was particularly
> > handy when I was new to a given language.  After that, the code
> > pretty much just fell into place.  Development was thusly made
> > easier.
> >
> > On the maintenance side, having accurate comments really make
> > doing enchancements a lot easier, rather than flicking back and
> > forth between code and manuals.
>
>  And the modern iteration of doing this is called Test Driven
>  Development -- instead of comments, you write tests first, then the
>  code to make them pass.

And my iteration is just like those except that it doesn't use comments
or tests.  But other than that it's just like the two above. ;-)

>  Done right, it's a really effective form of executable documentation
>  laying out the intentions of the application.

The problem is that it's rarely done right.  I think I'd prefer the
"comment first" method, since in my experience it more often tends to
be a lot more readable than so-called documentation generated from
code.

YMMV