Code comments as Documentation

[jsokohl -at- mac -dot- com]

Hi all,
This is more a pondering comment, rather than a question. I'm working on a
software design description. Developers are responsible for describing &
documenting the software modules that make up the program. They've decided
to use code comments (both header & inline) to make up the info that
describes the modules. They extract the comments with a script to produce
this doc. This dynamic approach means the doc can be as up to date as the
code is (assuming, of course, they edit their own comments whenever they
make significant changes).

My conern is in what to do with the doc I receive. Do I edit it to make
the often obtuse and sometime grammatically incorrect
developer-originating comments comprehensible, or do I let sleeping code
comments lie?
* If I edit them, then they immediately differ from what's in the code.
* If I ask 'em to add the edited text back into their code, they do double
work (and they're already frightfully resentful of having to do
documentation of their code in the first place--this dev  environment's
rampant with the "just read the damn code" mentality).

Bother.

joe

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl

WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed! http://www.webworks.com/techwr-l 

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.