Re: Inline Documentation, Part I

Subject: Re: Inline Documentation, Part I
From: "Gerard M. Vignes" <gmv0570 -at- UCS -dot- USL -dot- EDU>
Date: Wed, 14 Apr 1993 01:35:48 -0500

> subject: Re: Inline Documentation, Part I
> from: Ed Blachman x4420 <edb -at- fairport -dot- hq -dot- ileaf -dot- com>
> to: techwr-l
> date: Apr 13, 1993 (16:23 on Tue)

> I should say upfront that I'm a programmer, that I believe strongly in
> the value of inline documentation, and that I sometimes don't follow
> through on that belief. Notwithstanding my personal record in that
> area, I think Gerard's discussion (or at least part I, which is all
> I've seen so far) is well taken. However, I can't resist quibbling...

Actually, you aren't quibbling at all. I should have stated
that I was distinguishing between three types of documentation
which normally appear in a source listing:
(1) the module (or file) header,
(2) the function headers,
(3) and the inline comments.

I have violared one of the more important rules
of technical writing,

"If you are not certain that the reader will use
the same definition for a term as you are using,
then state your definition of that term."

Sorry about that, Ed :-)

> Sometimes I can be certain that there is higher-level documentation
> available -- stuff that explains the purpose of the application or the
> chief data structures. But not always, especially at the beginning of
> a project (when IMO it is most crucial to write inline doc). The best
> solution is to write enough conceptual doc to minimize the bulk of the
> inline stuff -- but sometimes the schedule doesn't allow that.

In this example, I have presumed that the module and function
headers are present and serving their intended purposes.

Oops! It seems I've been making lots of assumptions without
bothering to inform anyone else.

I will continue this exercise assuming the following.

(1) Any higher-level description, such as application
or system level documentation, exists and is adequate.

(2) This exercise covers a single module (source) file,
where "module" is a cohesive conceptual unit such
as an abstract-data-type stack or an interprocess
communications software-layer.

(3) The source file has the following format:


(other stuff)


(other stuff)

(block of code)



Where MODULE HEADER describes the purpose and use
of the module in terms of data and functionality.

FUNCTION HEADER describes the inputs, outputs,
and black-box processing of the function;

and INLINE COMMENT describes the method and reasoning
behind a block of programming language statements,
with "block" being defined as a sequence of statements
or a control structure (if-then-endif, do-continue, etc.).

Gerard Vignes
University of Southwestern Louisiana
USL P.O. Box 42709
Lafayette, LA 70504

Gerard Vignes USL PO Box 42709, Lafayette, LA, 70427

Previous by Author: Designing for Human error (was re: unsubscring)
Next by Author: RE: Disaster Recovery
Previous by Thread: Re: Inline Documentation, Part I
Next by Thread: Re: Inline Documentation, Part I

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

Sponsored Ads