\section{Guidelines for Writing Distributed Software}

\subsection{Names of Routines}

The first concern is not to use a name that is already being used.
To check if the name exists on the /ys tree on an Ultrix machine, you can
use the symbol `chk\_name'.  Here is an example (note that the .PRO
portion is required):
%
\ultrixinputa{chk\_name yodat.pro}
%
On a VMS machine, the following command should work:
%
\vmsinputa{dir ys:[...]yodat.pro}
%
It is possible to do the search from within IDL on any of the 
machines using a command like:
%
\idlinputa{print, path\_lib('yodat')}	\index{PATH\_LIB}
\idlinputB{3}{print, path\_lib('yo*')  }{;for all routines beginning with `yo'}
\idlinputb{pr\_path\_lib, 'yo*'}
%
The second concern is use care when chosing the name.  It should not be
general enough to cause conflicts or confusion between all of the other
instrument teams.  For example, the original name of SXT\_DECOMP was
DECOMP.  Every instrument has a decompression routine, so the name of
the instrument needs to be incorporated in the name of the routine for
general routines.  The name of the routine should not be shorter than
four letters and less than 14 characters (so that IDL can
compile it properly).  Underscores are acceptable, and the file
name should be all lower case.

The GT\_ routines are a unique set of routines meant solely for the
extraction of data out of a Yohkoh data structure.  
Normally, routines should have the name GET\_ unless it is designed to 
extract data from one fo the Yohkoh data structures.

\subsection{Calling Sequence}

It is the desire to have the calling sequence be {\bf index,data} for
all routines that require the index and data.  Please try to avoid having
any calling sequence of the form {\it data,index}.

In general, positional parameters should be used for any input which is
required for the procedure.  Keyword parameters should be used for the
optional parameters.

\subsection{Standard Headers}

The following standard IDL should be included at the top of each routine.  It
can be found in the file \$DIR\_GEN\_DOC/idl\_template.  Every line between ``;+''
and ``;-'' will be printed to the screen by the DOC\_LIBRARY utility.

\newpage
\begin{verbatim}
;+
; NAME:
; PURPOSE:
; CATEGORY:
; CALLING SEQUENCE:
; INPUTS:
; OPTIONAL INPUT PARAMETERS:
; OUTPUTS:
; OPTIONAL OUTPUT PARAMETERS:
; COMMON BLOCKS:
; SIDE EFFECTS:
; RESTRICTIONS:
; PROCEDURE:
; MODIFICATION HISTORY:
;-
\end{verbatim}

\subsection{Modularize}
Instead of making large main programs, try to break the program up into
smaller general purpose procedures or functions.  Other users will be able
to use your routines as building blocks, avoids duplication, and it allows for single point
maintenance.

\subsection{Portability}
It is important to have all software be portable between different computers
and different operating systems.  One of the biggest mistakes is use of
full file names with directories.  Since the software needs to work
on VMS and Unix machines, use the routine CONCAT\_DIR, to concatenate
a logical directory name and a file name.
For example, the command
%
\idlinputa{outfil = concat\_dir('\$DIR\_GEN\_OBS', 'obs92\_40a.01')} \index{CONCAT\_DIR}
%
returns `\$DIR\_GEN\_OBS/obs92\_40a.01' and 
\mbox{`\$DIR\_GEN\_OBS:obs92\_40a.01'} for VMS and Unix machines, respectively.
Always use logicals pointing to files in the YS directory area; do not 
write software that points to personal files since those may not be 
available at other sites.

\subsection{Don't Hardwire to Fixed Units}
Use /GET\_LUN on the file open statements, and /FREE on the window commands
%
\idlinputA{3}{openr, lun, filename, /get\_lun}{;GOOD EXAMPLE}
\idlinputB{3}{openr, 1, filename}{;BAD EXAMPLE}
%
