Re: Documentation from uncommented C Code

[Len Olszewski <saslpo -at- UNX -dot- SAS -dot- COM>]

In article <199702141801 -dot- NAA20578 -at- clarinet -dot- synapse -dot- net>, Susan Brown
<sbrown -at- jscsys -dot- com> writes:
|> Hi, Hi!!

Hi, yourself! 8-)

[...]

|>         Three questions:
|>
|>         1) Do any of you know of any C tools that will parse files
|> (including includes) for Global variable definitions and usage????

I can't help here, except to suggest that with enough time and effort
and a knowledge of PERL, or other text handling languages, you could
code this yourself and pass the source files to extract this information.
This assumes that the modules were coded according to some standard, and
standard structures were used to accomplish common tasks.

|>         2) Any general tips on constructing technical/maintenance references
|>         from uncommented code?

I take it you have no design specs. If you do, start there.

It helps if you have the programmer available to answer questions.

If you do, your first step should be to develop "retrospective"
functional specs. Find out what the code is supposed to do overall, how
the inputs need to be specified, what are the expected outputs and
behavior, and how the code handles common error conditions. Find out any
coding standards at the shop, standard grammar files, standard
declarations, and any scraps of information dealing with the subroutine
library.

After that, you need to discover how the code operates at the top design
level, determining what each major module of the code (to the extent you
can identify the major modules) *does* during compile and execution. You
need to figure out input and output requirements for each module, and
characterize the processing that occurs in between.

With this general top level description in hand, time to see your
developer: ask her "Is this right?". Then just repeat this exercise at
finer levels of detail until it makes sense to stop.

No developer there? Gee, I hope you know how to interpret code
correctly!

|>         3) More generally, how often have you faced this, and how do
|>         you cope with it?

I've dealt with this before, but not for production code. I documented
uncommented code on a number of occasions for the purpose of providing
examples for users. In other words, I wanted to show how to accomplish
something, and someone gave me code that did it. I then described how it
worked in the context of an example in a reference book. The idea was to
show a technique, not document how to maintain that particular code
itself.

I never had to document code for procedural purposes, where my analysis
would be used by others to maintain the product.

As a programmer, I have often been asked to assume maintenance for
undocumented code. The first thing I did in these situations was to go
through the exercise I've noted above and insert my own comments.

You might want to search the web for "white box testing" or "code
inspection". These are testing methodologies which, when properly
applied, enable you to exercise all of the statements and subroutines in
a piece of code for the purpose of constructing QA-type test-cases. The
principles apply to investigative work too, except instead of assessing
whether expected behavior results from an input configuration, you are
experimenting to see what behavior actually occurs.

It really does help if you have the developer there just to ask her.
Barring that, you need to get your hands dirty and experiment, but in an
organized fashion that starts at the top, and subdivides into smaller
units.

Good luck!
--
Len O.                    EXISTENTIAL SODA:
saslpo -at- unx -dot- sas -dot- com        Have young, drink fun, be Pepsi.

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html