Re: Source Code documentation?

Subject: Re: Source Code documentation?
From: iluvvscotties -at- earthlink -dot- net
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 12 Apr 2001 15:27:41 -0400

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.


Previous by Author: RE: thank-you notes
Next by Author: Re: Source Code Documentation
Previous by Thread: Re: Source Code documentation?
Next by Thread: Re: thank-you notes


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


Sponsored Ads