On Thu, 24 May 2001, Olin Lathrop wrote:

> I pretty much agree with you.  I've never had a customer that told me not to
> document something.  If they had, it would have been my responsibility to at
> least make sure they understand all the implications of that.  I might also
> decide that I don't want any part of that job.

And I wouldn't blame you.  You surely don't want your name associated with
a bungled project when someone else (or even you) needs to try to decipher
a few years from now what you've done, but has to start from scratch due
to lack of comments or docs.

> Most of the customers are not sophisticated enough to insist on particular
> documentation.  I document what I think makes sense, and most of the time
> they don't read it.  But I know how it will save their butt two years later
> when someone else might pick up the project.  The funny thing is that when
> the documentation is done right, the customer will never really notice and
> therefore appreciate it.  That's just part of the job.  Bad documentation,
> however, will eventually be noticed.  Unfortunately that often happens too
> late for there to be serious reprocussions to the perpetrator.
>
> I consider most of the documentation I create to be an integral part of the
> overall job.  Good code comments don't take time, they save time.

Amen.  I will be the first to admit I probably don't comment as much as
you do, but I at least document what is going on and why so it's not a
guessing game when I look at the code after a week.

Dale
--
A train stops at a train station.  A bus stops at a bus station.
On my desk I have a workstation...

--
http://www.piclist.com#nomail Going offline? Don't AutoReply us!
email listserv@mitvma.mit.edu with SET PICList DIGEST in the body