Re: Code Documentation

Subject: Re: Code Documentation
From: Jim Aikens <jaikens -at- ZOOMIT -dot- COM>
Date: Tue, 3 Nov 1998 16:51:00 -0500

Tracey Moore wrote:
>we now need to document the code.
>How do you document?

But who are you documenting it for? If it is for programmers, then I can
only urge that you forget about creating a document. It is wasteful and
dangerous to document program code externally. My very strong opinion (after
some years as a systems development manager in another life) is that source
code must be documented internally -- that is, in source code comments. At
least then there is a slight chance it will be read by the next person to
work on that code; there is also a chance (much slighter) that it will also
be updated when the code is changed.

Getting programmer's to actually write meaningful comments may be difficult;
getting them to worry about updating other documents, however, will probably
be impossible. The presence of adequate internal documentation should be a
part of any source code control system.

An external document can be useful for providing an overview of the pieces
and how they fit together, but anyone working on an individual piece is
going to want their documentation right before their eyes -- a form of
online help.

All of which reminds me of the contract programmer who once worked for me
and, when ordered to document the modules he had worked on, simply added the
comment "Self-explanatory" to each one. They may not be, but adequate
comments can make them so.

jim aikens

From ??? -at- ??? Sun Jan 00 00:00:00 0000=

Previous by Author: Re: Beginning a job search
Next by Author: Comma rules and the imperative
Previous by Thread: Re: Code Documentation
Next by Thread: Re: Code Documentation

What this post helpful? Share it with friends and colleagues:

Sponsored Ads