From: Bill Kelly <billk@...>
Date: 2005-04-28T05:48:08+09:00
Subject: Re: Comments Are More Important Than Code

From: "Barry Sperling" <barry@angleinc.com>
> 
> Sy wrote:
> > 
> > Just who would be writing and maintaining all that "commenting"
> > anyways?  The programmer is who.. so its style follows the
> > programmer's mindset.. concise.. so they can move on to the next real
> > issue --> more programming.
[...]
> The coders ARE the ones who can document the choice of algorithms and 
> explain why the function was written at all.  I've had to work on a lot 
> of legacy, undocumented code and it is difficult. It wastes more of my 
> time that it would have taken the writer to describe things well.

... "Yeahbut."  I'd take a completely undocumented codebase
developed test-first, over the most lavishly documented 
"traditional style" legacy codebase any day.

Not that I'm against useful comments.  But have you ever
_seen_ what happens to code when developed test-first?
The result is small, testable routines that do one thing,
in a verifiable way, with minimal dependence on external
state.

So my point is that addressing the problem of obnoxious
untestable "ball of mud" style legacy code systems by
prescribing bundles of documentation to go with them. . .
is more like a band-aid on the problem, or treating the
symptoms rather than addressing the underlying.. eh,
illness.  :)


Just $0.02

Regards,

Bill