Re: Code Documentation

Subject: Re: Code Documentation
From: JIMCHEVAL <JIMCHEVAL -at- AOL -dot- COM>
Date: Tue, 14 Apr 1998 12:22:58 EDT

In a message dated 4/14/98 10:31:58 AM EST, Debbie_Stewart -at- SIECOR -dot- COM writes:

<< We have hundreds of COBOL programs here and I am being assigned the task
to
inventory and document them. Fun, huh? Because of Y2K and turnover,
we have a need to get some control on the business critical programs.

Does anyone out there have a list, template, or process they use to
document existing code? >>
New or existing, I've always tried to get a few basics in:

- The name of the program/routine (COBOL enforces this and some of the other
pieces automatically, unlike lots of other languages)
- Who wrote it and when
- Who modified it and when (hard to recover after, though)
- What it does
- What program or JCL calls it
- What programs it calls

Data elements should be (briefly) defined in terms of their real-world
meaning.

Every main and calling routine should have an explanation of its purpose at
the start. If a routine is longer than a page (or a screen or two),
explanations should appear for each major function within it. (I've been known
to go to almost pseudo-code level here, but in fact that can get cluttered if
you're not careful.)

I can't imagine a 'template' per se for all this, since the overall form of
the program is pretty much established before you document it.

Jim Chevallier
Los Angeles
==Visit Chez Jim: Jim Chevallier's home page - htpp://www.gis.net/~jimcheval
====




Previous by Author: Re: Using OR as a verb
Next by Author: Re: TechWrite Organization Names
Previous by Thread: Code Documentation
Next by Thread: Re: Code Documentation


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

Sponsored Ads


Sponsored Ads