Subject: RE: business case for mechanized documentation
From: Rich Morin <>
Date: Tue, 11 Apr 2006 13:15:11 -0800

At 1:22 PM -0600 4/11/06, Anderson, Kelly wrote:
> I also read the Test Driven Development list, where we discuss
> part of extreme programming (XP), and we had a discussion there
> of late as to whether even comments in the code are helpful. The
> consensus there is that they are not, and that comments are a
> "code smell" that should be refactored into more readable code.

XP has not yet contributed a substantial portion of the Open Source
code base.  It remains to be seen whether it will do so.  If this
notion reflects the best thinking in the XP community, I'm not at
all confident that it will (or should).

As I understand it, both Agile and Extreme Programming rely on lots
of testing, refactoring, etc.  Knowing about the coverage and status
of your tests is critical; if a program can harvest, analyze, and
present this information, the process gets easier and more reliable.

Similar notions apply to refactoring.  Indeed, if you move all of
your comments into your method names, a documentation generator will
have lots of material to work with.  And, given that Agile Languages
tend to be big on introspection, it may be possible to harvest useful
information from running programs.  Of course, the usual caveats
about code coverage metrics apply...

--            Rich Morin     +1 650-873-7841

Technical editing and writing, programming, and web development