Standards for GEN Simulation Software
		=====================================
		James J. Kelly, jjkelly@physics.umd.edu
		Last revised: 5 Oct 99

	Efficient development of software by a team of programmers
working independently upon a wide variety of platforms requires each 
component to adhere to strict standards of portability.  Unfortunately,
these standards have not yet been formulated with sufficient clarity
or completeness; consequently, I have had to make extensive revision
of submitted software during its assimilation.  This document updates
the software standards and will be revised as needed.  Please review
these standards carefully and forward to me suggestions for additions
or revisions.   


Language
--------
Standard Fortran 77 with only minimal extensions.  The only extensions
likely to work on all platforms are: long file names and generic
function references.

DO NOT USE:
a) extended fortran compiler options, such as fortran/extend
b) compiler directives, such as nolist, in include statements
c) exclamation points for inline comments
d) extended line lengths -- most compilers will truncate statements
   after column 72
e) VMS fortran extensions


Text preparation
----------------
Use standard fortran column formatting.  Column 1 is reserved for the
comment character, columns 2-5 for line numbering, column 6 for a
continuation character, and columns 7-72 for statements.  Try to make
your code readable by others.  

DO NOT USE:
a) tabs -- they are not portable
b) exclamation points for inline comments
c) characters beyond column 72
d) implied continuation


Parameter statements
--------------------
The dimensions of important arrays should be declared as parameters
in an include file, with related dimensions computed in subsequent
parameter statements.  Important physical constants should also be
defined in parameter statements.


Data statements
---------------
	Do not place DATA statements in include files.  That practice 
causes "multiple declaration" errors if the include file is referenced 
more than once.  It is better to collect DATA statements in separate
initialization subroutines.  Do not hard-code large blocks of constants 
or parameters; rather, use data files for this purpose.  These data
files should be read by an initialization subroutine that is called
only once.


Include files
-------------
Should have basic names without explicit directories or environment
variables.


IMPLICIT NONE
-------------
This statement can be valuable for program development, but unless
it is used consistently by every member of the team, it would interfere
with the shared include files.  Therefore, avoid this statement until
further notice.


Subprograms
-----------
	Subprograms should require a minimum number of arguments.  
Each subprogram should be well documented internally, including its 
a) purpose, b) method, c) assumptions, d) required information, and 
e) steps.  Because we probably will not have time to produce
external documentation before the code is completed, it is important
that colleagues can understand and use your code.  Use informative
variable names, even if lengthy.
	Most data should be obtained from common storage, such as the 
ntuples and parameters defined in the include file.  Each subprogram 
should perform one, or most a few, well-defined operations upon the 
event data.  Thus, generation of an event consists of a logical sequence 
of steps performed by calls to subprograms with useful and informative
names, but few arguments.


Global variables
-----------------
	Neutron variables are stored in a real*4 array event_n which can
be written as a row-wise ntuple using HBOOK library routines.  Similarly,
electron variables are stored in event_e.  These arrays may be combined 
and/or extended later later.
	Specific variables in an ntuple array are accessed using indices
defined by parameter statements within the include file.  This method
provides considerable flexibility and minimizes variable conflicts 
when several developers write subprograms simultaneously but
independently.  


Local variables
---------------
	Typically a subprogram will retrieve the quantities it needs using 
statements like
	px = event_n(index_n_px1)
where the index that refers to a neutron variable X is index_n_X.
After performing calculations on local variables, the subprogram
updates or adds quantities to the ntuple by
	event_n(index_n_X) = X.



--------------------------------------------------------------------