Re: Source Code documentation?

[iluvvscotties -at- earthlink -dot- net]

At 12:03 PM 04/11/2001 +0530, SATISH RAJ H wrote:
>My organization requires me to do source code documen-
>tation in Delphi...What I need is methodologies/strategies
>Till date, I am used to doing end user documentation.
>Source code documentation, (I feel!) is a different cup of tea
> Not sure how to go about with it. A few tips would be great

Although I have not yet used Delphi, I have documented a ton of source code 
over the years, so I hope that the following will help you.

The main difference is that of your target audience.  Whereas some of your 
novice users may be barely unable to distinguish between a monitor and a 
keyboard (don't laugh; a colleague once had a user complain that his system 
was lousy and it was all his fault ... "I kept pressing the [HELP] key, but 
you never came!"), source code documentation is written for developers, who 
will understand basic programming tenets, such terms as algorithms, etc.

However, your reader may not be familiar with that particular software 
language ... Most experienced developers/programmers can relate horror 
stories about garbage they inherited and were expected to repair or 
enhance, despite the fact that there were no manuals or third party books 
available (and, before the internet, you couldn't even track them down) in 
languages they'd never heard of before.

Another difference is that source code documentation is usually 
incorporated into the code, rather than presented as a separate document or 
booklet.  Every language has at least one character which the code ignores, 
and which is thus used for comments/documentation.  Since the main function 
of source code documentation is to enable a developer to modify a procedure 
(or to use it as a template), this will dramatically expedite matters for 
him or her.

When I document my code, I just try to make it clear -- both to me (in case 
I have to change or correct it) and to any successor who may have to do so. 
(The latter obviously requires more detail, since s/he would have no way of 
knowing what I was thinking of.)

The main thing to remember is that you have to make it clear to someone who 
may have to modify it several years from now, and who won't have a clue 
what you did, or why you did it.  S/he will have to know the 
purpose/function of each segment, a description of each variable or array, etc.

If you're writing the code yourself, I would strongly suggest using 
standardized naming conventions.  There are many books available which 
describe this -- but, the main point is to be clear and consistent.  For 
example, a variable named ThisMonthNum would be understandable (i.e., 04 
for April) even if it doesn't follow any standardized 
convention.  Conversely, a variable of A1 would be unclear to virtually 
anybody (and, yes, some programmers code their work in that manner -- sans 
documentation -- to make themselves appear indispensable).  If that is not 
an option, at least try to be consistent, and define anything that won't be 
self-explanatory.

I don't have a generic sample in front of me (although I think I included 
this as part of a Borland conference presentation several years ago, so can 
probably dig out a sample if you need it).  I will also E-Mail you an 
actual sample of documented source code (much too long to attach).  Feel 
free to E-Mail me if I can be of any further help.

However, off the top of my head (and assuming that ' prefaces anything that 
the code will ignore):
''********************************************
MY LATEST PROC (proc name)
'Purpose of proc ...
'Variables declared (list each one, alone with its function, whether or not 
it is global, etc.
'Arrays declared (same as above)
'*********************************************
Proc MyProc
        (MyParameter1, 'function of this parameter
        MyParameter2)  'function of this parameter
'-------------------------------------
'Define such-and-such
'-------------------------------------
jklfkladdkl
akaklaljk
'------------------------------------
'Print results
'------------------------------------
kldkldskld
alkl;akdfjkl
EndProc


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems 
Available 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com

Sponsored by DigiPub Solutions Corp, producers of PDF 2001 Conference East, 
June 4-6, Baltimore, MD. Now covering Acrobat 5. Early registration deadline 
April 27. http://www.pdfconference.com. 

---
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.