TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
> QUOTE FROM MESSAGE
> 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.
-----------------------------------------
| FUNCTION HEADER |
-----------------------------------------
...
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
