Re: Software that retrieves developer comments from code

[Sandy Harris <pashley -at- storm -dot- ca>]

gdwarner -at- mindspring -dot- com wrote:

> You could have one of your VB programmers
> write a little application that ...
> 
> You might even be able to do this in Word
> (Tools --> Macros --> Visual Basic Editor).

A few comments on this.

You probably don't want all the comments. Some
are needed only by a programmer who is working
on the code and (at least arguably) don't belong
in the documentation. That needs only the comments
directed at users of the code.

If that is correct, the easiest method is to pick
some special format for extractable comments. One
I've seen used is what I suggested in previous
message, for C:

/*
 * This is extractable
 * It can be multi-line
 */

Your extractor can then grab those while ignoring
other comments. Doing this is trivial. Getting
the programmers to use it correctly may not be :-) 

You probably do want some things that are not
comments, in particular the declarations of key
data structures and any externally visible
functions. Some of these may be in header files
rather than the main source code files.

On the other hand, there are things you should
not extract because they aren't part of the
interface. In particular, static data structures
or functions are not designed to be accessed  
by the user and should not be documented.

Toss the above or something like it at your
development manager and see what he or she
has to say. Any competent programmer should be
able to produce the tool in an afternoon. I can
do a simple one in 5 minutes; see previous post.

However, that isn't the hard part. A production
quality version, tested, debugged, documented, 
... could be a couple of weeks work, but even
that isn't the hard part.

The hard part is determining -- for your code,
your developers, and your audience -- exactly
what should be extracted. Then what changes to
your coding standards do you need to support
the extraction. (For C, there might be some
thorny issues around use of const, static, 
extern, ...) Then how is compliance with that
checked and ...

The development manager is the only one likely
to be able to answer those questions.

At least in simple cases, a well-commented
header file may be all you need. If that's
done right, the header may tell another programmer
everything he needs to use the code.

e.g. Here's one of mine where I've tried to do
that: 

/*
 * header file for using Rijndael in a random number
 * generator. Sandy Harris <sandy -at- storm -dot- ca>
 */

/*
 * adjust if required for your machine
 */ 
typedef unsigned char u1byte ; /*  8-bit unsigned       */
typedef unsigned int  u4byte ; /* 32-bit unsigned       */

/*
 * public interface to the random generator
 *
 * all functions return a value which should be
 * checked by the caller
 *
 * Fill a buffer with 32-bit random words
 * returns
 *    a pointer to the buffer on success
 *    NULL on failure
 */
u4byte *rrandom(u4byte *buffer, u4byte words) ;

/*
 * All other functions give
 *      0 for failure
 *      1 for success
 *
 * initialise generator
 * must be called before generator is used
 *
 * the argument controls how much to churn
 * things (by calling rr_self_rekey()) before
 * starting output
 *
 * paranoids can set it non-zero
 *
 * the generator is designed to be safe even
 * if it is zero
 */
int rrandom_init(u4byte) ;
/*
 * close down generator
 */
int rrandom_close() ;
/*
 * two functions to control re-keying
 *
 * you should never need to call these
 * since the generator re-keys itself
 * automatically
 *
 * we provide them for the paranoids
 *
 * full_rekey() uses real random input from /dev/random
 * self_rekey() uses generator output to rekey itself
 */ 
int rr_full_rekey() ;
int rr_self_rekey() ;

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
PC Magazine gives RoboHelp Office 2002 five stars - a perfect score!
"The ultimate developer's tool for designing help systems. A product
no professional help designer should be without." Check out RoboHelp at
http://www.ehelp.com/techwr
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.