Wiki Home

Source Code Header 4 dot PRGs

Namespace: WIN_COM_API
It is a widely held opinion that a good programmer documents his/her .PRG's with a header of comments, (briefly) describing what the .PRG does/uses/calls.
Here's what I've done for years, starting in dBaseII and morphed to FPD: Randy Bosma
* PROGRAM X.prg ()
*  Programmer..: Fox Programmer       Date: __.___.19__
*  Description.: (brief, followed by enviroment presumptions)
*  Written for.: FPD2.6
*  Usage.......: DO x
*  Called by...: (name of calling file(s), to a point)
*  Calls:......: (other functions and procedures)
*  Parameters..: (listed and described)
*  Uses........: (.DBFs used)
*  Returns.....: (for functions)
*  Example.....: (where the Usage line does not make it perfectly clear)
*  Rev.Hist.:  By:   Changes:
*  dd.mmm.yy       - 
*  EOF() .PRG
*  EOProc  x  IN  .PRG
*  EOFunc  x  IN  .PRG

Just want to point out that in VFP 7, it's really easy to create IntelliSense Custom Scripts to pop all that into your PRG when you type some specified string like "header".

Can you please post an example?

Did you click on the link to IntelliSense Custom Scripts? Several there should give you an excellent start to creating a script. Also, refer to the Foxcode Object Reference topic in the help file to see how to limit the script to running in only PRG's, for example. -- Nancy Folsom
Please share what you do for your VFP .PRG header....
Nadya Nosonovsky: I have this simple header, but I'm thinking about modifying it:
* Description.......:
* Calling Samples...:
* Parameter List....:
* Created by........:
* Modified by.......:
How applicable is this still? I don't use procedure files anymore, except as relics (I don't mean that badly, just factually). Additionally, dynamic procedure files shared between developers is becoming more and more rare. This will probably be an unpopular postion, but I've never found headers like this to be particularly useful with the exception of a calling sample which is great. Visual Source Safe becomes the modification audit trail and is more accessible than buried in a PRG.

The first example is longer than many of my method codes and I prefer SelfDocumentingCode. So, for example, visual classes should use the the description available for every class and method and property (which is available as text by using viewing the class as code). For code based classes, something similar. Often at the top of a class PRG, I'll included examples of how to use the class.
-- Nancy Folsom

I recently had one of my off-the-wall code comments come back to haunt me, in a potentially useful way. At a particular job, I used to insert the comment "Prayers to appropriate deities - David" at the beginning of every .prg file, since I said that humourously on every compile attempt. Several years later now, my former manager called me to see if I was interested in working on a project with him, and it was because he kept running into that comment in all those .prg files that he remembered me.

In a more serious note, while I believe in self-documenting code, having a header documenting the intent of the method and well-placed comments summarizing the intent of particular points in the code are good things. The primary danger is that of reading the comments instead of the code, which will throw one off the track of a bug as often as not.
-- David Stowell

I like a header at the top of every PRG. For methods, I usually use just an opening comment, but I like an About or zReadMe method in each class, which is all comments and contains documentation for the class. -- Tamar Granor
As suggested for CodeBook 6.2
*---------------- Location Section ---------------------
*} Library: 
*} Class:   
*} Method:  
*) Description:
*------------------- Usage Section ---------------------
*$ Scope:       
*$ Parameters:  
*$ Usage:       
*$ Example:     
*$ Returns:     
*----------------- Maintenance Section -----------------
*@ Precondition Invariants:
*@ Post-condition Invariants:
*? To Do:
*= Methods Called:
** Process:
*^ Change Log:

Here's a method header found in some public domain code
*============================================================================== paraEtc - or valid values etc. *==============================================================================
Contributors: Randy Bosma Nadya Nosonovsky Nancy Folsom David Stowell
Category Code Samples Category Best Practices
( Topic last updated: 2003.08.07 11:26:32 AM )