path: root/doc/std.ms

.RP
.TL
IRAF Standards and Conventions
.AU
Elwood Downey
George Jacoby
Vesa Junkkarinen
Steve Ridgway
Paul Schmidtke
Charles Slaughter
Douglas Tody
Francisco Valdes
.AI
.K2 "" "" "*"
August 1983
.AB
Clearly defined and consistently applied standards and conventions are
essential in reducing the "number of degrees of freedom" which a user
or programmer must deal with when using a large system.
The IRAF system and applications software is being built in accord with
the standards and conventions described in this document.  These include
system wide standards for data structures and files, standard coding
practices, coding standards, and standards for documentation.
Wherever possible, the IRAF project has adopted or adapted existing
standards and conventions that are in widespread use in other systems.
.AE
.NH
Introduction
.PP
Clearly defined and consistently applied standards and conventions are
essential in reducing the "number of degrees of freedom" which a user
or programmer must deal with when using a large system.  The user benefits
from consistently applied naming conventions for packages and tasks,
and from a logical and consistently applied scheme for ordering the
parameters to a task.  The programmer who must read code written by
other programmers benefits from the application of good programming
practices and a uniform style.
.PP
The IRAF system and applications software is being built in accord with
the standards and conventions described in this document.  These include
system wide standards for data structures and files, coding standards,
standards for numerical libraries, and standards for documentation.
.PP
Whenever possible, the IRAF project has adopted or adapted existing
standards and conventions that are in widespread use in other systems.
Examples are the standard filename extensions, which are adopted from
UNIX (the IRAF software development system), and the coding standard
for the SPP language, which is consistent with the coding standard
for the C language, on which the design of the SPP language was based.

.NH 2
Official Acceptance Procedure
.PP
Software developed by programmers outside of the IRAF group
must conform to the standards presented in this document to be accepted
as a supported product, or to be included in the IRAF distribution.
.PP
Software developed by programmers within the IRAF group will be
inspected periodically by another member of the IRAF group to check
for adherence to the standards, for constructs that could cause
transportability problems, and to ensure that the code is upwards
compatible with future versions of the SPP language compiler and program
libraries.  IRAF group members will gladly provide this service to
anyone outside the group who would like to have their code checked.


.NH
System Standards
.PP
This section defines those standards and conventions which pervade the
system.  An example of such a fundamental convention is one-indexing.
Others include the standard for generating and using virtual file names,
and the procedure naming convention for the system libraries.

.NH 2
Standard Data Structures
.PP
This section describes the fundamental data structures used by the
IRAF system and applications tasks.  An IRAF applications package
should not access data structures other than those described here.
Applications may build their own high level structures upon text or
binary files if necessary, but the standard high level structures
(particularly the imagefile and the datafile) should be used when
applicable.
.NH 3
Text and Binary Files
.PP
The most primitive data structure in the IRAF system is the file.
At the most basic level there are two types of files, \fItext files\fR
and \fIbinary files\fR.
.PP
\fBText files\fR may contain only character data.  The fundamental unit of
storage is the line of text.  Character data in text files is maintained
in a form which is OS (operating system) dependent, and text files may
be edited, printed, and so on with the utilities provided by the host OS.
Character data is stored in text files in the character set of the host
OS, which is not necessarily ASCII.  Text files are normally accessed
sequentially, and writing is permitted only at EOF (end of file).
.PP
Examples of text files include program source files, CL parameter
files, list files, ASCII card image files, CL script files, and the
session logfile.  Text files are often used for descriptor files which
are read at run time by table driven software.
.PP
\fBBinary files\fR are read and written only by IRAF tasks.  The fundamental
unit of storage is the \fIchar\fR.  Data is stored in binary files in
the form in which it appears internally in IRAF tasks, without any form
of type conversion.  Binary files are generally not transportable between
different machines.  Binary files may (normally) be read and written at
random.
.PP
Any device which supports reads and writes in some form may be made to
appear to be a binary file, subject to possible restrictions on seeks
and writing at EOF.  FIO (the IRAF file i/o package) supports devices
of arbitrary blocksize, and i/o to binary files is very efficient
and may be optimized according to the type of access expected.
.PP
Examples of binary files include imagefiles, datafiles, a graphics stream,
a FITS file, and memory.
.PP
Although a binary file may be used to store any kind of data, including
text, files which contain only text should be maintained as text files.
.NH 3
Parameter Files
.PP
The \fBparameter file\fR, a text file, is used to store the parameters
and associated information (type, mode, prompt, default value, etc.)
for a task.  Parameter files are read and written by the CL, and are
normally invisible both to the user and to the applications task.
.PP
The \fIdefault\fR parameter file for a task must reside in the same directory
as the executable file or script file associated with the task.  The
root name of the parameter file is the name of the task.  Parameter files
have the extension ".par".
.PP
The logical directory \fBuparm\fR should be defined by the user to provide
a place to store \fIupdated\fR versions of parameter files.  When updating
a parameter file, the CL will prepend the first two characters of the
package name to the parameter file name (to avoid redefinitions), and save
the resultant file in \fBuparm\fR.  This package prefix should be omitted
from the names of default parameter files in the package directory.

.RS
.TS
il l.
task.par	default parameter file
pk\(ultask.par	updated parameter file (package \fIpk...\fR)
.TE
.RE

.NH 3
Imagefiles
.PP
The \fBimagefile\fR is used to store bulk data arrays of arbitrary
dimension, size, and datatype.  Images of up to seven dimensions are
currently supported.  The length of a dimension is limited by the
size of a long integer on the host machine.  A full range of datatypes,
from unsigned char through complex, are supported.
.PP
The fundamental unit of storage for an imagefile is the \fIpixel\fR.
All the pixels in an image must be of the same datatype.  The dimensions,
size, and datatype of an image are fixed when the image is created.
.NH 4
standard nomenclature for images
.PP
The axes of a two dimensional image divide the image into \fIlines\fR
and \fIcolumns\fR.  A three dimensional image consists of one or more
\fIbands\fR, each of which is a two dimensional image, all of which
are the same size and datatype.
.PP
The names of procedures, variables, and so on in software which accesses
images should be derived from the standard names \fBline\fR, \fBcolumn\fR,
\fBband\fR, and \fBpixel\fR.  The use of the term \fIrow\fR in place of
\fIline\fR is discouraged, despite the historical use of \fIrow\fR at KNPO.
The \fIline\fR, \fIcolumn\fR, \fIband\fR nomenclature is a defacto
international standard, not only in the image processing literature,
but at most astronomical data reduction centers as well.
.PP
Examples of standard identifiers include \fInlines\fR, \fIncols\fR,
\fInpix\fR, and \fIndim\fR, referring respectively to the number of lines,
columns, pixels, or dimensions to be operated upon.
.NH 4
definition of a pixel
.PP
Given an image of dimension N, a \fIpixel\fR is defined as the datum
whose coordinates within the image are given by the subscript [x1,x2,...,xN],
where the first index in each dimension has the value one, and where
\fBi\fR is the \fIcolumn\fR index, \fBj\fR the \fIline\fR index, \fBk\fR
the band index, and so on.  The dimensionality of the image is given by
the number of subscripts.  The value of a pixel is \fInot\fR a dimension.
.PP
If an array of pixels is to be interpolated, the question of the extent
or size of a pixel arises.  In the IRAF system a pixel is defined as
a mathematical point, and has no extent.  This is in contrast to some
other systems, which have adopted the "physical" definition of a pixel,
i.e., pixel \fIi\fR is assumed to extend from [i\(mi0.5] to [i+0.5].
.PP
Thus, given an array of N pixels, an IRAF interpolant will return an
indefinite value at the points [1\(mieps] and [N+eps], where \fIeps\fR
is a very small number.  An array of N pixels contains N\(mi1 subintervals.
If an array of N pixels is expanded by interpolating every 0.5 pixels,
an array of 2N\(mi1 pixels will result.  Mapping an array of N pixels into
an array of 2N pixels requires a stepsize of (N\(mi1)/(2N\(mi1) pixel units.
.NH 3
Datafiles
.PP
The \fBdatafile\fR provides a \fIdatabase management\fR capability for
the IRAF system.  The datafile is used to store \fBrecords\fR.  A record
consists of an ordered set of \fBfields\fR, each of which has a name,
a datatype, and a value.  The structure of a datafile is defined by the
applications program, and a description of that structure is saved in
the datafile itself.  It is this self describing nature of datafiles
which makes database management possible.
.PP
The datafile has many advantages over the old technique of writing an
array of binary records in a headerless file, via FIO \fBwrite\fR calls.
Datafiles are self documenting, can be manipulated by the standard
database management tools, and the structure of the records in a datafile
can be modified as a program evolves, without losing the capability to
access old datafiles.
.NH 3
List Files
.PP
The \fBlist file\fR is a text file, each line of which comprises one
element of the list.  Lists are used to drive tasks in batch or semibatch
mode.  A typical list defines a set of files, images, records, coordinates of
objects, etc. to be processed by a task.
.PP
Lists should be maintained as text files to take advantage of the ability
of the CL to process text files.  Lists maintained in text form can
be created by i/o redirection, and are easily edited, sorted, filtered,
inspected, and so on.  Lists can be input to tasks using list structured
parameters, redirection of the standard input, and templates.
.NH 3
FITS
.PP
The FITS standard of the AAS and IAU [1] is the standard format for
image data entering and leaving the IRAF system.  The FITS format will be
used both for image data transmitted by magnetic tape between machines, and for
image data transmitted between machines by other means (i.e., via a network).
.PP
Proposed extensions to the FITS standard may provide a means for transmitting
tabular data (such as a list), as well as an efficient means for transporting
text files.  These extensions will be implemented in the IRAF system when a
draft standard is received from the FITS standards committee of the AAS.

.NH 2
Virtual File Names
.PP
A file name may be specified in a machine independent fashion, or as
an OS dependent pathname.  A machine independent filename is called a
\fBvirtual file name\fR (VFN).  The ability of the system to deal with
OS dependent filenames is intended primarily as a convenience feature
for the user.  Applications programs and CL script tasks should be
written in terms of virtual file names for maximum transportability.
.PP
A virtual file name has the following form:

.nf
.RS
\fIldir$root.extn\fR
.RE

where
.RS
.TS
ci ci
lw(1.0i) l.
field	usage

ldir	logical directory or device name
root	root or base file name
extn	extension denoting the type of file
.TE
.RE
.fi

.PP
The \fIldir\fR and \fIextn\fR fields are optional.  The logical directory
field, if present, must be delimited by the character $.  The backslash
character can be used to escape characters such as $, if required in
OS dependent filenames.
.PP
The root and extension fields may contain up to 20 characters selected
from the set [a-zA-Z0-9\(ul+\(mi#.].
A file name may not contain any whitespace.
The extension field should not exceed three characters.
The extension field is separated from the root field by the character "." (dot).
If the root field contains one or more occurrences of the dot character,
the final dot delimited field is understood to be the extension, and the
remaining fields are considered to be part of the root.
.PP
Purely numeric filenames are legal virtual file names.  If the first
character of a file name is a digit, the character "I" will be prepended
to generate the OS pathname.  Thus, the filenames "I23" and "23" refer to
the same file.  Numeric filenames are reserved for use by the user as a
convenient way to name imagefiles, and should not be used in programs
or script tasks.

.NH 2
Standard Filename Extensions
.PP
A number of standard filename extensions are defined to identify those
types of files which are most commonly used in IRAF programs and by
users of the IRAF system.
These extensions reflect the selection of UNIX
as the IRAF software development system, but transportability is not
compromised since the extension field is part of a VFN (and is therefore
mapped in a machine dependent way).

.RS
.TS
center box;
cb s
c | c
l | l.
Standard Filename Extensions
=
Extension	Usage
_
\\.a	archive or library file
\\.c	C language source
\\.cl	Command Language script file
\\.com	global common declaration
\\.df	IRAF datafile
\\.f	Fortran 77 source
\\.h	SPP header file (contains global \fIdefines\fR)
\\.hlp	\fILroff\fR format help text
\\.ms	\fITroff\fR format text
\\.o	object module
\\.par	CL parameter file
\\.pix	pixel storage file (part of an imagefile)
\\.s	assembler language source
\\.x	SPP language source
.TE
.RE

.PP
Note that no extension is assigned for executable files (executable files
are not directly accessed by IRAF programs or utilities).
Certain of these extensions may have to be mapped into a different form
in the process of converting a VFN to an OSFN (i.e., on most operating
systems, ".a", ".f", ".o", and ".s" will be mapped into some other
extension at file access time by the system interface routine \fIzmapfn\fR).

.NH 2
One Indexing
.PP
The IRAF system is one-indexed.  This convention is applied without
exception in the system software, and should be applied equally rigorously
in applications code.  Past systems (i.e., the KPNO IPPS system and 
the original KPNO Forth Camera system) have shown that mixing zero and
one indexing in the same system is confusing, and is the source of many
errors.
.PP
Note that the one-indexing convention applies to both numbering systems
and offsets.  Thus, the coordinates of the first pixel in a two dimensional
image are [1,1], and the offset of the first character in a file is also
one.  Scaling an offset involves subtracting the constant one, a multiply
or divide to perform the actual scaling, followed by the addition of the
constant one.
.PP
The awkwardness of one-indexing for calculating offsets (in comparison
with zero-indexing) is balanced by the logical simplicity of one-indexed
numbering schemes.  The one-indexing convention was selected for IRAF
because numbering schemes are more visible to the user than is offset
arithmetic, and because IRAF is a Fortran based system.

.NH 2
The Procedure Naming Convention for the System Libraries
.PP
With the exception of certain "language" level identifiers (\fBopen\fR,
\fBclose\fR, \fBread\fR, \fBwrite\fR, \fBmap\fR, \fBerror\fR, etc.),
all procedures in the packages comprising the IRAF program and system
interfaces are named according to a simple convention.
.PP
The purpose of the procedure naming convention is to make procedure name
selection logical and predictable, and to minimize collisions with the
names of the procedures (and other external identifiers) used in applications
programs.  This latter problem is a serious matter in a large system which
is Fortran based, due to the global nature of all procedure and global common
names, and the restriction to six character identifiers.
.PP
The procedure naming convention should \fInot\fR be used to generate
names for procedures in applications code.  The procedure naming
convention purposely results in rather obscure identifiers.  This is
necessary for system library routines, to minimize the possibility of
collisions, but at the highest level (in applications code and in CL
packages), readability is the most important consideration.
.PP
The names of system library procedures are generated by concatenating
the following fields:

.nf
	\fIpackage\(ulprefix\fR \(sl\(sl \fIopcode\fR \(sl\(sl \fItype\(ulsuffix\fR
.fi

.PP
The package prefix identifies the package to which the procedure belongs,
and is one to three characters in length.  The opcode is a concise
representation of the function performed by the procedure.  The type suffix
identifies the datatype of the function value or primary operand.
.PP
An example of the use of the procedure naming convention is the generic
function \fBclgpar\fR, in the CLIO package.  In this case, the package prefix
is "cl", the opcode is "g" (get), and the (abstract) type suffix is "par".
The generic function \fBclgpar\fR is implemented with the following set of 
typed procedures:

.nf
	\fBclgpar\fR \(-> clgetb, clgetc, clgets, clgeti, clgetl, clgetr, clgetd, clgetx

or, more concisely,

	\fBclgpar\fR \(-> clget[bcsilrdx]
.fi
.NH 3
Orthogonality
.PP
The procedure naming convention is an example of a three dimensional
"orthogonal" naming convention.  The VAX instruction set and associated
mnemonics are another example.  As we have seen, often two dimensions are
sufficient (no type suffix) to encode the names of the procedures in a
package.  Occasionally it is necessary to have more than three dimensions,
as in the following example from the image i/o package:  

.nf
	\fBgetpix\fR, \fBputpix\fR \(-> im[gp][pls][123][silrdx]

where the fields have the following significance:

	im[get/put][pixel/line/section][dimension][datatype]
.fi

.PP
The five dimensional expression on the right side represents a total of 108
possible procedure names (\fIimgp1s\fR, etc.).
A \fBgetpix\fR or \fBputpix\fR statement is easily converted into a call
to the appropriate low level Fortran subprogram by analyzing the subscript
and applying the above generating function.
.NH 3
Standard package prefixes
.PP
A table of the package prefixes for the packages comprising the IRAF
system libraries is shown below.

.TS
center box;
cb s s
ci | ci
l | l l.
Standard Package Prefixes
=
package	prefix
_
CLIO	cl	command language i/o
FIO	f	file i/o
MEMIO	m (or mem)	memory i/o
VSIO	v	virtual structure i/o
IMIO	im	image i/o
MTIO	mt	magtape i/o
GIO	g	graphics i/o
VOPS (1-dim)	a	vector operators
VOPS (2-dim)	m	matrix operators

byte primitives	byt
char utilities	chr
error handling	err (or xer)
pattern matching	pat
string utilities	str
process control	t
exception handling	x
OS interface	z
.TE

.NH 3
Standard type suffixes
.PP
The type suffix is optional, and is used when the operator is implemented
for several different types of data.  The type suffix is a single character
for the primary data types, but may be up to three characters for the
abstract data types ("file", "string", etc.).  The standard type suffixes
are as follows:

.TS
center box;
cb s s
c | c s
l | l l.
Standard Type Suffixes
=
datatype	suffix
_
\fBbool\fR	b	(primary types)
\fBchar\fR	c
\fBshort\fR	s
\fBint\fR	i
\fBlong\fR	l
\fBreal\fR	r
\fBdouble\fR	d
\fBcomplex\fR	x
_
file	fil	(abstract types)
string	str
cursor	cur
CL parameter	par
character constant	cc
.TE

.NH 2
Mapping of External Identifiers
.PP
The SPP language maps identifiers longer than the six characters permitted
by the Fortran standard into identifiers of six or fewer characters.
Both local and external identifiers are mapped.  The mapping convention
applies to all procedures in the system libraries.
.PP
A simple, fixed mapping is used to facilitate the use of symbolic debuggers
without having to resort to a compiler listing.  A simple mapping convention
also makes it easier for the programmer to foresee possible redefinitions.
.PP
The mapping function used is known as the "5+1" rule.  The six character
Fortran identifier is formed by concatenating the first five characters
and the last character of the long identifier from the SPP source code.
Underscore characters are ignored.
.PP
Identifiers in SPP source code should be chosen to maximize readability,
without concern for the length of an identifier.  The compiler will
flag spelling errors and identifiers which map to the same six character
Fortran identifier (if both identifiers are referenced in the same file).

.KS
Examples:
.TS
center;
ci ci s
l c l.
XPP identifier	Fortran identifier

strmatch	STRMAH	(library procedure)
read\(ultemplate	READTE	(procedure)
get\(ulkeyword	GETKED	(procedure)
ival\(ulalready\(ulused	IVALAD	(boolean variable)
days\(ulper\(ulyear	DAYSPR	(integer variable)
.TE
.KE

.NH 2
Conventions for Ordering Argument Lists
.PP
The convention for ordering argument lists applies to both CL tasks
and compiled procedures.  This convention should serve only as a
guideline: in practice, other considerations (such as symmetry) may
produce a more natural ordering.
.PP
Argument lists may contain operands and their dimensions, objects
used for working storage, control parameters, and status return
values (organized in that order).
The types of operands may be further broken down into those which
are input and those which are output, ordered with the input parameters
at the left and the output parameters at the right.
.PP
More precisely, the ordering of operands and parameters in the argument
lists of procedures and tasks is as follows:

.RS
.IP (1)
The principal operand or operands (data objects) dealt with by the
procedure, ordered with input at the left and output at the right.
Examples of primary operands include file names, file descriptors,
image header pointers, vectors, and so on.
.IP (2)
Dimension parameters, offsets, position vectors, or other objects which
can be considered part of the specification of an operand.  If the operands
in (1) are individually dimensioned, the dimension argument(s) should
immediately follow the associated operand.  If several operands share
the same dimension arguments, these arguments should follow the last
operand in the group.
.IP (3)
Objects used for working storage, and their dimensions.
.IP (4)
Any control parameters, flags, options, etc., used to direct the operation
of the procedure.  Unless there is another ordering which is clearly more
logical, these should be arranged in alphabetical order.
.IP (5)
Status return parameter or parameters, if any.
.RE

.PP
Argument lists should be kept as short as possible if they are to be
easily remembered by the programmer (ideally, no more than three arguments).
Short argument lists decrease the coupling between modules, increasing
modularity and making programs easier to modify.  Any procedure which
requires more than five arguments should be carefully examined to see
if it should be broken into several smaller procedures.


.NH
Coding Standards
.PP
Programs are read far more often than they are written.  The readability
of a program is a function of the \fBstyle\fR in which it is written.
The effectiveness of a particular style in enhancing the readability of
a program is increased when that style is applied consistently throughout
the entire program.  The readability of the code within a \fIsystem\fR
is maximized when a single, well designed style is applied consistently
throughout the system.  Since large systems are written by many people
(though often read by a single person), it is necessary to document the
standard programming style for the system, as clearly as can be done.
.PP
The standard programming style for a system is a major part of the
\fBcoding standard\fR for that system (though not the whole story).
The benefits and difficulties of coding standards are well summarized by
the following excerpt from a paper describing the evolution of the
\fIIngres\fR data base management system [2]:

.QP
\fI"The initial reaction was exceedingly negative.  Programmers used to
having an address space of their own felt an encroachment on their personal
freedom.  In spite of this reaction, we enforced standards that in the
end became surprisingly popular.  Basically, our programmers had to recognize
the importance of making code easier to transfer to new people, and that
coding standards were a low price to pay for this advantage..."\fR
.QP
\fI"Coding standards should be drawn up by a single person to ensure
unity of design; however, input should be solicited from all programmers.
Once legislated, the standards should be rigidly adhered to."\fR

.PP
The standard language for IRAF system and applications code is the Subset
Preprocessor Language (SPP), which was patterned after the C language of
Kernighan and Ritchie [3].  Much of the text in the following pages was
taken almost verbatim from reference [4], which defines the coding standard
adopted at Bell Labs for the C language.  Since such a well defined (and
widely used) standard already exists, we have adopted the C coding
standard as the core of the standard for the SPP language.

.NH 2
General Guidelines
.PP
In this section we discuss the philosophy governing the decomposition of
the IRAF system into packages and tasks.  The same principles are seen to
apply to the decomposition of tasks or programs into separately compiled
procedures.
.PP
Our intent here is to summarize the structural characteristics expected
of a finished applications package.  Once a package has been coded and
tested, however, it is too late to change its structure.  The functional
decomposition of a package or program into a set of modules, the selection
of names for the modules, and the definition of the parameters of each
module, is the purpose of the detailed design process.  A discussion of
the techniques and tools used to perform a detailed design is beyond the
scope of this document.
.NH 3
Packages and Tasks
.PP
The IRAF system and applications code is organized into \fBpackages\fR,
each of which operates upon a particular kind of data.  These packages are
independent, or are loosely coupled by the datafiles, imagefiles, or lists
on which they operate.
.PP
Close coupling between packages (for example, by means of specialized
data structures) should be avoided.  Leave the coupling of modules from
different packages to the user, or write high level script tasks ("canned"
procedures) to streamline commonly performed operations, \fIafter\fR the
packages involved have been designed and coded.
.PP
A package consists of a set of \fBtasks\fR, each of which should perform
a \fIsingle function\fR, and all of which operate on the package data
structures.  The name of each task should be carefully chosen to identify
the function performed by the task (a novice user should be able to guess
what function the task performs without having to read the documentation).
Command names should not be abbreviated to the point where they have
meaning only to the package designer.
.PP
The tasks in a package should be \fIdata coupled\fR, meaning that
their operation is defined entirely in terms of the package data
structures.  Avoid \fIcontrol coupling\fR, which occurs when one task
controls the functioning of another by passing a control parameter or
switch.  A task should not modify another tasks parameters, nor should
it modify its own input parameters.
.PP
A CL callable task may reference its own local parameters, plus two
levels of \fBglobal parameters\fR (the package parameters and the CL
parameters).  Global parameters should be used with care to avoid tasks
which are highly coupled.  For example, if a task were to use the the CL
"scratch" parameters \fBi\fR and \fBj\fR for loop control variables,
that task would be strongly coupled to any other task in the system,
now and in the future, which also references the global parameters
\fBi\fR and \fBj\fR (with disastrous results).  The CL scratch parameters
are provided for the convenience of the user: they should not be used
by tasks.
.PP
Global parameters can actually reduce the coupling between tasks when
the alternative would be to add a parameter to the set of local parameters
for each task in the package.  Such parameters are normally set only by
the user (or by a user script task), and are \fIread only\fR to all tasks
in the package.  Examples of such parameters might be the names of the
package datafiles, or parameters which describe the general characteristics
of the data to be operated upon.  If in doubt, use a local parameter
instead of a global parameter.
.PP
A task may be implemented as a \fBscript task\fR, written in the CL, or as
a compiled procedure or \fBprogram\fR, written in the SPP language.
Any number of related or unrelated programs may be linked together to form
a single executable \fBprocess\fR.  The decision to implement a task
in the CL or in the SPP language is irrelevant to the package designer,
as is the grouping of programs to form physical processes.
.NH 3
Procedures
.PP
The guidelines for implementing a program as a set of separately
compiled \fBprocedures\fR are similar to those for decomposing a package
into a set of tasks.  \fIEach procedure should perform a single function,
should be well named, should be data coupled, and should have as few
parameters as possible\fR.
.PP
Procedures which perform a single function are less complex than multiple
function procedures, tend to be less strongly coupled to their callers,
and are more likely to be useful elsewhere in the program, and in future
programs.  A program structured as a hierarchy of single function,
minimally coupled procedures is highly modular, and generally much easier
to modify, than a program consisting of multiple function (monolithic),
strongly coupled procedures.  Reducing the coupling between procedures
makes it less likely that a change to one procedure will affect the
functioning of another procedure somewhere else in the system.
.PP
It has long been argued that a monolithic procedure is more efficient
than one which calls external procedures to perform subfunctions.
While there is some truth to this claim, efficiency is only one of the
measures of the quality of software.  Other factors such as reliability,
robustness, flexibility, transportability, simplicity, and modifiability
are often more important.  Furthermore, it is almost always true that
five or ten percent of the code accounts for ninety percent of the
execution time, and it will prove easier to optimize that five or ten
percent of the code if it is in the form of isolated, single function
procedures (a small, simple procedure is easily replaced by an equivalent
routine written in assembler, for example).
.PP
A section of code which is common to two or more modules, which is
\fBfunctional\fR (performs a single, well defined function), and which is
not strongly coupled to the rest of the code in the parent module,
should be extracted to form a separate module.  Not only does this
reduce the amount of code which must be tested and debugged, it also 
makes the program easier to modify, since only a single section of code
must be changed to modify the function in question.
.PP
Less obviously, a section of code should be extracted to form a new module
even if the new module is only called from one other module, if the new
module is functional, and is likely to be useful in future programs.
A new module should also be created if doing so removes a sizable
section of code from the parent module, significantly reducing the complexity
of the parent module (provided the new module is functional and not
strongly coupled).  If the control flow of a procedure is so deeply nested
that statements will no longer fit on a line, that is an indication that
code should be extracted to form a new module.
.PP
The name of a procedure, like that of a task, should be carefully
selected to identify the function performed by the procedure.
\fIThe function of each subprocedure referenced by a procedure should
be evident to the reader, without having to go look up the source for
the individual subprocedures\fR.  For similar reasons, the function of
each of the \fBarguments\fR of a subprocedure should be evident without
having to look up the source or documentation for the procedure.
The \fBdefine\fR feature of the SPP language is particularly useful
for parameterizing argument lists.
.PP
Reducing the number of arguments to a procedure reduces the coupling
of the procedure to its callers, making the procedure easier to modify
and use, reducing the possibility of a calling error, and usually
increasing the functionality (usefulness) of the procedure.  Most
procedures should have no more than three arguments: procedures with
more than five arguments should be examined to see if they should be
decomposed into several smaller procedures.
.PP
Psychologists have shown that one 8\(12 by 11 inch sheet of paper
(i.e., one page of a computer listing) contains about the amount of
information that most people can comfortably handle at one time.
Procedures larger than one or two pages should be examined to see
if they should be broken down further.  Conversely, procedures which
contain fewer than five lines of code should be examined to see if
they should be merged into their callers.  If a procedure contains
more than ten declarations for local variables or arrays, that is
another indication that the procedure probably needs to be decomposed
into smaller functional units.
.PP
A program is more resistant to changes in the external environment
(and therefore more transportable) if that part of the program which
interfaces to the outside world is isolated from the part which processes
the data.  This tends to happen automatically if the "single function"
guideline is followed, but nonetheless one should be consciously aware
of the need to \fIisolate those portions of a program which get parameters,
access external data structures, and format the output results\fR.
.PP
Numerical routines, transformations, and so on should almost always
be implemented as separate procedures.  These are precisely those parts
of a program which are most likely to be useful in future programs,
and they are also among the most likely to be modified, or replaced
by functionally equivalent modules, as the program evolves.

.NH 2
Languages
.PP
The standard language for IRAF systems and applications code is the SPP
language [5], which is mechanically translated into Fortran during compilation.
Fortran itself may be used for purely numerical routines (no i/o) which
are called from programs written in the SPP language.
.PP
IRAF programs must be written in the SPP language, rather than Fortran,
because the routines in the IRAF i/o libraries are callable only from the
SPP language.  The IRAF i/o libraries are interfaced to the SPP language
because they are \fIwritten\fR in the SPP language.
.NH 3
The SPP Language
.PP
The IRAF Subset Preprocessor language (SPP) implements a subset of the 
full language scheduled for development in 1984.  The SPP language is
defined by the SPP Reference Manual [5].  Be warned that present compilers
for the SPP language accept constructs that are not permitted by the
language standard.  As better compilers become available, programs using
such constructs (i.e., parenthesis instead of brackets for array subscripts),
will no longer compile.  If you are not sure what the language standard
permits, have your code checked periodically by someone who is familiar
with the standard.
.NH 3
The Fortran Language
.PP
The Fortran language is defined by the ANSI standards document ANSI X3.9-1978
[6].  Be warned that most Fortran compilers accept constructs that are
not permitted by the language standard.  When a Fortran module developed
on one machine is ported to another, programs using such constructs
(i.e., the DO WHILE and TYPE constructs provided by the DEC Fortran
compilers), will no longer compile, or will run incorrectly.
.PP
Fortran is used in IRAF applications only for numerical subroutines and
functions, such as mathematical library routines.  The following Fortran
statements should not be used in Fortran subprograms that are to be called
from an IRAF program (use of one of these statements would probably
result in a loader error):

.DS
all statements which involve i/o
CHARACTER
BLOCK DATA
(blank) COMMON
PAUSE
PROGRAM
STOP
.DE

.PP
The SPP datatypes \fBint\fR, \fBreal\fR, \fBdouble\fR, and \fBcomplex\fR
are equivalent to the Fortran datatypes INTEGER, REAL, DOUBLE PRECISION,
and COMPLEX.  These are the only datatypes which should be used in IRAF
callable Fortran modules.
.PP
There is no single widely accepted coding standard for the Fortran language.
Fortran code being ported into the IRAF system should remain in the
form in which it was originally written, except for the removal of 
the statements listed above.  If extensive modifications are required,
the modules should be recoded in the SPP language.  All new software
should be written in the SPP language.

.NH 2
Standard Interfaces
.PP
The programmer should be familiar with the routines in the packages
comprising the IRAF program interface, and should use these routines where
applicable.  This practice reduces the amount of code which must be
written and debugged, and simplifies the task of the newcomer who must
read and understand the code for the package.  Furthermore, optimizations
are often possible in system library routines which would be inappropriate
or difficult to perform in applications modules.
.PP
Only procedures which appear in the documentation for a package (the
\fBexternal specifications\fR of the package) should be called from
programs external to the package.  The external specifications
of a package define the \fBinterface\fR to the package.  The major
interfaces of a large system are normally documented and frozen early
in the lifetime of the system.  Freezing an interface means that its
external specifications stop changing; \fIthe internal specifications of the
code beneath the interface can and will continue to change as the system
evolves\fR.
.PP
Calling one of the internal, undocumented procedures in a package,
or directly accessing the internal package data structures, is known
as \fBbypassing\fR or \fBviolating the interface\fR.  Violating an
interface is a serious matter because it results in code which works
when it is coded and tested, but which mysteriously fails some months
later when the programmer responsible for maintaining the called package
releases a new version which has been modified internally, even though
its external specifications have not changed.
.PP
Interfaces are often violated, albeit unintentionally, when a programmer
copies the source for one of the documented procedures in a package,
changes the name, and modifies it to do his bidding.  This may result in
the programmer getting his or her job done a bit faster, but must be
avoided at all costs because sooner or later the resultant software system
is going to fail.
.PP
Worse yet, there is no guarantee that when the failure occurs, it will
occur in that part of the system written by the programmer who violated
the interface.  Activation of the offending module may corrupt the
internals of the called package, resulting at some indefinite point later
in an apparently unrelated error, which may be difficult to trace back
to the module which originally violated the interface.  Typically,
the error will appear only infrequently, when the system is exercised
in a certain way.
.PP
Violating interfaces results in an \fIunreliable system\fR.  If such a
problem as that described above happens very often, the systems
programmer charged with maintaining the system will become afraid to
change systems code, and the result will be a system which is hard to
modify, and which will eventually have to be frozen internally as well
as externally.  At that point the system will no longer be able to evolve
and grow, and eventually it will die.
.PP
Other common ways in which interfaces are violated include communicating
directly with the host operating system (bypassing the system interface),
communicating directly with the CL, or sending explicit escape sequences
to a terminal.  If one were to access an external image format by calling
C routines interfaced directly to UNIX, for example, one would be bypassing
the system interface, and the transportability of the applications program
which did so would be seriously compromised.
.PP
The CL interface may be violated by sending an explicit command to the CL,
by reading from CLIN or writing to CLOUT, or by directly accessing the
contents of a parameter file.  Sending a command to the CL violates the
CL interface because a task must know quite a bit about the syntax of
an acceptable CL command, as well as the capabilities of the CL, to send
such a command.
.PP
From the point of view of a task, the CL is simply a data structure,
the fields of which (parameters) are accessed via \fBclget\fR and
\fBclput\fR procedures.  Programs which do not expect the CL to be
anything more than a data structure will be immune to changes in the CL
as it evolves.  In the future we might well have several different
command languages, each with a different syntax and capabilities.
An IRAF task which does not attempt to bypass the CL interface will
be executable from any of these command languages, without modification
or even recompilation.

.NH 2
Package Organization
.PP
Each package should be maintained in its own directory or set of directories.
The name of the \fBpackage directory\fR should be the name of the package,
or a suitable abbreviation.
.PP
A package consists of source files (".x", ".f", ".cl", ".h", ".com"),
documentation (".hlp" and ".ms" files), parameter files (".par"),
and executable modules.  If the package is small it will be most convenient
to maintain the package in a single directory.  The package directory should
contain a file named "Readme" or "README", describing the function of the
package, and refering the reader to more detailed package documentation.
.PP
If a package is too large to be maintained in a single directory, two
subdirectories named \fBbin\fR and \fBdoc\fR should be created.  The
package directory should contain the sources, the Readme file, and
a file named "Makefile" if \fIMake\fR is used to maintain the package.
The \fBbin\fR directory should contain the executable files and the
default parameter files (the CL requires that these be placed in the
same directory).  The \fBdoc\fR directory should contain the design
documentation, reference manuals, user's guides, and manual pages.
.PP
The programmer should develop and maintain a package in directories
located within the programmer's own directory system.  When the package
is released, an identical set of directories will be created within the
IRAF directory system.  Subsequent releases of new versions of the package
will be a simple matter of copying the files comprising the new package
into the IRAF directories, and documenting the differences between the
old and new versions of the package.
.PP
This procedure makes a clear distinction between the current release of
the package and the experimental version, buffering the user from constant
changes in the software, yet giving the programmer freedom to experiment
and develop the software at will.

.NH 2
Tasks and Processes
.PP
The \fBtask\fR statement of the SPP language is used to group one or
more compiled tasks (programs) together to form an executable process.
As noted earlier (\(sc3.1.1), the grouping together of programs to
form a physical process is a detail which is irrelevant to the structure
of the package.
.PP
The grouping of several programs together to form a single process can,
however, result in significant savings in disk space by replacing a
number of executable files by a single (slightly larger) file.
The same technique can also have a significant impact on the efficiency of
a CL script, by eliminating the overhead of process initiation required when
each task called by the CL resides in a different executable file.
In the case of a simple task which executes in a few tens of milliseconds,
the overhead of process initiation could easily exceed the time required
to actually execute the task by one or two orders of magnitude.
.PP
The user of a package may well wish to change the way in which programs
are grouped together to form processes, in order to minimize the overhead
of process initiation when the programs are executed in a sequence peculiar
to the user's application.  To make it easier to modify the grouping of
tasks to form processes, the \fBtask\fR statement should be placed in
a file by itself, rather than including it in the file containing the
source for a program.
.PP
In other words, \fIthe task statement should be decoupled from the source
for the programs which it references\fR.  If this is done, then regrouping
is a simple matter of editing the file containing the task statement,
editing the package script task (which associates tasks with executable
files), and compiling the new task statement.

.NH 2
File Organization
.PP
Each program or task in a package should be placed in a separate file.
The name of the file should be the same as the name of the top level module
in the file.  This practice makes it easy to locate the source for a module,
and speeds compilations.  The \fIMake\fR and \fIMklib\fR utilities are
particularly useful for automatically maintaining programs and libraries 
consisting of many small files.
.PP
A file consists of various sections that should be separated by several
blank lines.  The sections should be organized as follows:

.RS
.IP (1)
Any header file includes should be the first thing in the file.
.IP (2)
A prologue describing the contents of the file should immediately follow
the includes.  If the prologue exceeds four lines of text, it should be
enclosed in \fB.help\fR ... \fB.endhelp\fR delimiters, rather than making
each line of text a comment line.  Large blocks of texts are easier to
edit if maintained as help blocks, and placing such program documentation
in a help block makes it accessible to the online \fBhelp\fR utilities.
.IP (3)
Any parameter or macro definitions that apply to the file as a whole
are next.
.IP (4)
The procedures come last.  They should be in a meaningful order.
Top-down is generally better than bottom up, and a "breadth-first"
approach (functions on a similar level of abstraction together) is
preferred over depth-first (functions defined as soon as possible after
their calls).  Considerable judgment is called for here.  If defining
large numbers of essentially independent utility procedures, consider
alphabetical order.
.RE

.NH 2
Header Files
.PP
Header files are files that are included in other files prior to
compilation of the main file.  A header file contains a number of
\fBdefine\fR statements, defining symbolically the constants,
structures, and macros used by a subsystem.
Some header files are defined at the system level,
like \fI<imhdr.h>\fR which must be included in any file which accesses
the image header structure.  Other header files are defined and used
within a single package.
.PP
Absolute pathnames should not be used to reference header files.
Use the \fI<name>\fR construction to reference system header files.
Non-system header files should be in the same directory as the source
files which reference them.  Header files should be functionally
organized, i.e., declarations for separate subsystems should be in
separate header files.  The name of the header file should be the same
as the name of the associated subsystem, and the extension should be ".h".
For example, if the name of a package were "imio", the package header
file would be named "imio.h".
.PP
Header files should not be nested.  Nesting header files can cause the
contents of a header file to be seen by the compiler more than once.
Furthermore, the dependence of a source file on a header file should
be made clear and explicit.  The pattern matching utilities (\fBmatch\fR
or \fBgrep\fR) are often used to search for the name of a particular
header file, to determine which source files are dependent upon it. 

.NH 2
Comments
.PP
Well structured code with self explanatory procedure and variable names
does not need to be extensively commented.  At a minimum, the contents
of the file should be described in the file prologue, and each procedure
in the file should be preceded by a comment block giving the name of the
procedure and describing what the procedure does.
.PP
Comments within the body of a procedure should not obscure the code.
Large procedures should be broken up into logical sections (groups
of statements which perform some function that can be understood in
the abstract), with one or more blank lines and (optionally) a comment
preceding each section.  The comment should be indented to the same
level as the code to which it refers.
.PP
The amount of commenting required depends on the complexity of the code.
Generally speaking, if a comment appears every five lines or less,
the code is either overcommented or too complex.  If a one page procedure
contains no comments, it is probably undercommented.
.PP
Short comments may appear on the same line as the code they describe,
but they should be tabbed over far enough to separate them from the
statements.  If more than one short comment appears in a block of code,
they should all be tabbed to the same column.


\fIExample 1:  Compute the mean and standard deviation of a sample.\fR
.DS
.cs 1 22
# Accumulate the sum and sum of squares of those pixels
# whose value is within range and not indefinite.
do i = 1, npix
    if (sample[i] != INDEF) {
        value = sample[i]
        if (value >= lcutoff && value <= hcutoff) {
            ngpix = ngpix + 1
            sum = sum + value
            sumsq = sumsq + value \(**\(** 2
        }
    }

# Compute the mean and standard deviation (sigma).
switch (ngpix) {
case 0:                         # no good pixels
    mean = INDEF
    sigma = INDEF
case 1:                         # exactly one good pixel
    mean = sum
    sigma = INDEF
default:
    mean = sum \(sl ngpix
    temp = sumsq \(sl (ngpix\(mi1) \(mi sum\(**\(**2 \(sl (ngpix \(** (ngpix\(mi1))
    if (temp < 0)               # possible with roundoff error
        sigma = 0.0
    else
        sigma = sqrt (temp)
}
.DE
.cs 1

.NH 2
Procedure Declarations
.PP
Each procedure should be preceded by several blank lines and a block
comment that gives the name of the procedure and a short description
of what the procedure does.  If extensive comments about the arguments
or algorithm employed are required, they should be placed in the
prologue rather than in the procedure itself.
.PP
The prologue should be followed by one or two blank lines, then the
\fBprocedure\fR statement, which should be left justified in column one.
A blank line should follow, followed by the declarations section,
then another blank line, and lastly the body of the procedure,
enclosed in left justified \fBbegin\fR ... \fBend\fR statements.
The declarations should start in column one, and the list of objects
in each declaration should begin at the first tab stop.  The body of
the procedure should be indented one full tab stop.
.PP
If the function of an argument, variable, or external function is
not obvious or is not documented in the prologue, it should be
declared alone on a line with an explanatory comment on the same line.
In general, well chosen identifiers are preferable to explanatory
comments, which tend to produce clutter, and which are more likely to
be misleading or wrong.  Arguments should be declared first,
followed by local variables and arrays, followed by function declarations,
with the \fBerrchk\fR declaration, common block includes,
string declarations, and \fBdata\fR initialization statements last.


\fIExample 2\fR
.DS
.cs 1 22
# ADVANCE\(ulTO\(ulHELP\(ulBLOCK -- Search a file for a help block
# (block of text preceded by ".help" left justified on a
# line).  Upon exit, the line buffer will contain the text
# for the help statement, if one is found.  EOF is returned
# for an unsuccessful search.

int procedure advance\(ulto\(ulhelp\(ulblock (fd, line\(ulbuffer)

int     fd                              # file to be searched
char    line\(ulbuffer[SZ\(ulLINE]
int     getline(), strmatch()
errchk  getline

begin
        while (getline (fd, line\(ulbuffer) != EOF)
            if (strmatch (line\(ulbuffer, "^.help") > 0)
                return (OK)

        return (EOF)
end
.DE
.cs 1


.NH 2
Statements
.PP
The format of both simple and compound statements is the same,
except that the body of a compound statement is enclosed in braces.
The body or executable part of a statement should begin on the second
line of the statement, and should be indented one more level than the
first line.  Each successive level should be indented four spaces more
than the preceding level (every other level is aligned on a tab stop).
The opening left brace should be at the end of the first line,
and the closing right brace should be alone on a line
(except in the case of \fBelse\fR and \fBuntil\fR),
indented to the same level as the initial keyword.
.NH 3
Statement Templates
.PP
Templates are shown only for the compound form of each statement.
To get the template for the non-compound form, omit the braces and
truncate the statement list to a single statement.  The \fBiferr\fR
statement is syntactically equivalent to the \fBif\fR statement, and
may be used wherever an \fBif\fR could be used.
.PP
If a compound statement extends for many lines, the readability of the
construct is often enhanced by inserting one or more blank lines into
the body of the compound statement.  In the case of a large \fBif else\fR,
for example, a blank line (and possibly a comment) might be added before
the \fBelse\fR clause.  Similarly, blank lines could be inserted before
an \fBelse if\fR, a \fBthen\fR, or a \fBcase\fR.

.cs 1 22
.DS
\fBif\fR (expr) {
    <statement>
    <statement>
}
.DE
.DS
\fBiferr\fR (statement) {
    <statement>
    <statement>
}
.DE
.DS
\fBiferr\fR {
    <statement>
    <statement>
} \fBthen\fR {
    <statement>
    <statement>
}
.DE
.DS
\fBif\fR (expr) {
    <statement>
    <statement>
} \fBelse\fR {
    <statement>
    <statement>
}
.DE
.cs 1

.PP
The \fBelse if\fR construct should be used for general multiway branching,
when the logical conditions for selecting a particular branch are too
complex to permit use of the \fBswitch case\fR construct.

.DS
.cs 1 22
\fBif\fR (expr) {
    <statement>
} \fBelse if\fR (expr) {
    <statement>
} \fBelse if\fR (expr) {
    <statement>
}
.DE
.cs 1

.PP
The \fBfor\fR statement is the most general looping construct.  The \fBdo\fR
construct should be used only to index arrays (i.e., for vector operations).
The value of the index of the \fBdo\fR loop is undefined outside the body
of the loop.  The \fBfor\fR statement should be used instead of the
\fBdo\fR if the loop index is needed after termination of the loop.
The \fBrepeat\fR construct, without the optional \fBuntil\fR, should be
used for "infinite" loops (terminated by \fBbreak\fR, \fBreturn\fR, etc.).

.DS
.cs 1 22
\fBfor\fR (i=1;  i <= MAX;  i=i+1) {
    <statement>
    <statement>
}
.DE
.DS
\fBdo\fR i = 1, npix {
    <statement>
    <statement>
}
.DE
.DS
\fBwhile\fR (expr) {
    <statement>
    <statement>
}
.DE
.DS
\fBrepeat\fR {
    <statement>
    <statement>
} \fBuntil\fR (expr)
.DE
.cs 1

.PP
The \fBswitch case\fR construct is preferred to \fBelse if\fR for a multiway
branch, but the cases must be integer constants.  The cases should not be
explicit or "magic" integer values; use symbolically defined constants.
Explicit character constants are permissible, but often it is best to define
character constants symbolically too.  A number of common character constants
are defined in the system include file \fI<chars.h>\fR.

.DS
.cs 1 22
\fBswitch\fR (expr) {
\fBcase\fR ABC:
    <statement>
\fBcase\fR DEF, GHI, JKL:
    <statement>
\fBdefault\fR:
    <statement>
}
.DE
.cs 1

.PP
The \fBprintf\fR statement is a compound statement, since the \fIparg\fR
calls are logically bound to the \fBprintf\fR.  Although braces are
not used, the body of the statement should be indented one level to make the
connection clear.  Printf statements must not be nested.

.DS
.cs 1 22
call \fBprintf\fR (format\(ulstring)
    <parg\(ulstatement>
    <parg\(ulstatement>
.DE
.cs 1

.PP
The \fBnull statement\fR should be used whenever a statement is required
by the syntax of the language, but the problem does not require that a
statement be executed.  Null cases are often added to switch statements
to reserve cases, even though the code to be executed for the case has
not yet been implemented.

\fIExample 3\fR
.DS
.cs 1 22
# Skip leading whitespace.
for (ip=1;  IS\(ulWHITE(str[ip]);  ip=ip+1)
    ;
.DE
.cs 1

.NH 2
Expressions
.PP
Whitespace should be distributed within an expression in a way
which emphasizes the major logical components of the expression.
For simple expressions, this means that all binary operators should
be separated from their operands by blanks.  In an argument list,
a blank should follow each comma.  Keywords and important structural
punctuation like the brace should be separated from the neighboring
left or right parenthesis by a blank.  Complex expressions are generally
clearer if whitespace is omitted from the "inner" expressions.

.KS
\fIExample 4:\fR

.RS
.nf
.cs 1 22
alpha = beta + zeta
a = (a + b) \(sl (c \(** d)
p = ((p\(mi1) \(** SZ\(ulDOUBLE) \(sl SZ\(ulINT + 1
IM\(ulPIXFILE(im) = open (filename, READ\(ulONLY, BINARY\(ulFILE)
a[i,j] = max(minval, min(maxval, a[i\(mi1,j]))
.fi
.RE
.KE
.cs 1

.PP
By convention, whitespace is omitted from all but the most complex
array subscript expressions, and the left square bracket is not
separated from the array name by a blank.  A unary operator should
not be separated from its operand by a blank.
.PP
The system include file \fI<ctype.h>\fR defines a set of macros which
should be used in expressions involving characters.  For example,
IS\(ulWHITE tests whether a character is a whitespace character
(see Example 3), IS\(ulDIGIT tests whether a character is a digit,
and IS\(ulALNUM tests whether a character is alphanumeric.

.NH 2
Constants
.PP
Numerical constants should not be coded directly.  The \fBdefine\fR
feature of the SPP language should be used to assign a meaningful name.
This practice does much to enhance the readability of code, and
also makes large programs considerably easier to modify, since one
need only change the \fIdefine\fR.  Defined constants which are referenced
by more than one file should be placed in an ".h" include file.
.PP
A number of numerical constants are predefined in the SPP language.
A full list is given in reference [5].  Some of the more commonly used
of these global constants are shown below.  To save space, those constants
pertaining to i/o (READ\(ulONLY, TEXT\(ulFILE, STDIN, STDOUT, etc.) are omitted,
as are the type codes (TY\(ulINT, TY\(ulREAL, etc.), and the type sizes
(SZ\(ulINT, SZ\(ulREAL, etc.).

.TS
box center;
cb s s
ci | ci | ci
l | c | l.
Selected Predefined Constants
=
constant	datatype	meaning
_
ARB	i	arbitrary dimension, i.e., "char lbuf[ARB]"
BOF, BOFL	i,l	beginning of file (use BOFL for seeks)
EOF, EOFL	i,l	end of file (use EOFL for seeks)
EOS	i	end of string
EPSILON	r	single precision machine epsilon
EPSILOND	d	double precision machine epsilon
ERR	i	error return code
INDEF	r	indefinite valued pixel
MAX\(ulEXPONENT	i	largest exponent
MAX\(ulINT	i	largest positive integer
MAX\(ulREAL	r	largest real number
NO	i	opposite of YES	
NULL	i	invalid pointer, etc.
OK	i	opposite of ERR
SZB\(ulCHAR	i	size of a char, in machine bytes
SZ\(ulFNAME	i	maximum size of a file name string
SZ\(ulLINE	i	maximum size of a line of text
SZ\(ulPATHNAME	i	maximum size of an OS pathname
YES	i	opposite of NO
.TE

.NH 2
Naming Conventions
.PP
Keywords, variable names, and procedure and function names should be
in lower case.  The names of macros and defined parameters should be
in upper case.  The prefix SZ, meaning \fBsizeof\fR, should be used
only to name objects which measure the \fIsize of an object in chars\fR.
Other prefixes like LEN, N, or MAX should be used to name objects which
describe the number of elements in an array or set.
.PP
For example, the system wide predefined constant SZ\(ulLINE defines the
maximum size of a line of text, in units of chars, while SZ\(ulFNAME
defines the maximum size of a file name string, also in chars.  Since
space in structures is allocated in struct units rather than chars,
the constant defining the size of the FIO file descriptor structure is
named LEN\(ulFIODES, \fInot\fR SZ\(ulFIODES.

.NH 1
Portability Considerations
.PP
IRAF programs tend to be highly transportable, due to the machine
and device independent nature of the SPP language and the program
interface libraries.
Nonetheless, it is possible (unintentionally or otherwise)
to produce machine or device dependent programs.
A detailed discussion of the most probable trouble areas follows.
The programmer should be aware of these pitfalls,
but highly transportable programs can be produced merely by
applying the following simple guidelines: \fI
(1) choose the simplest, not the cleverest solution,
(2) write modular, well structured programs, and
(3) use the standard interfaces.\fR
.NH 2
keep it simple
.PP
Simple, modular programs, structured according to the guidelines in \(sc3.1,
are easy to understand and modify.  Even the best programs are unlikely
to be completely portable, because they will only have been tested and
debugged on one or two systems by their author.
Therefore the transportability of a program is significantly increased
if it easy for someone who is unfamiliar with the code to quickly find
and fix any machine dependencies.  A package of \fBverification routines\fR
are extremely useful when testing software on a new system, and ideally
should be supplied with each package, along with sample output.
.NH 2
use the standard interfaces
.PP
Much care has gone into making the standard interfaces as machine and
device independent as possible.  By using the standard interfaces in
a straightforward, conventional fashion, one can concentrate on solving
the immediate problem with confidence that a highly transportable
and device independent program will automatically result.
.PP
The surest way to produce a machine or device dependent program is
to bypass an interface.  This fact is fairly obvious, but it is not
always easy to tell when an interface is being bypassed (see \(sc3.3
for examples).  Furthermore, by bypassing an interface, one may be able to
provide some feature that would be difficult or impossible to provide
using the standard interfaces.  In some cases this may be justified
(provided transportability is not a requirement),
but often the feature is cosmetic, and does not significantly increase
the functionality of the program.  The correct procedure is to
request that the interface causing the problem be extended or refined.
.NH 2
avoid machine dependent filenames
.PP
Machine dependent filenames should not appear in source files.
Files which are referenced at compile time, such as include files,
should be placed either in the package directory or in the system
library directory, to eliminate the need to use a pathname.
Program files accessed at runtime must be referenced with a pathname,
since the runtime current working directory is unpredictable.  
In this case a VFN should be used.  The logical directory for the VFN
should be defined in the package script task.
.NH 2
isolate those portions of a program which perform i/o
.PP
This fundamental principle is especially important when one attempts
to transport an applications program from one reduction and analysis
system to another, since the interfaces will almost certainly be quite
different in the two systems.
Encapsulating that part of the program which does i/o
reduces the amount of code which must be understood and changed
to bring up the package on the new system.
.NH 2
keep memory requirements to a reasonable level
.PP
Not all machines have large address spaces, nor do all machines have
virtual memory.  Virtual memory seems simple, but it is not; to use it
effectively one must know quite a bit about how virtual memory is
implemented by the local OS, and implementations of virtual memory by
different operating systems differ considerably in their characteristics
and capabilities.
Using virtual memory effectively is not just a matter of accessing
large arrays in storage order.  If one can do that, then there is little
justification for writing a program which is dependent on virtual
memory.
.PP
It is possible to write down a set of guidelines for using virtual
memory effectively and in a reasonably transportable manner,
if one considers only large virtual memory machines.
These guidelines are complex, however, and such a discussion is beyond the
scope of this document.
It must be recognized that any dependence on virtual memory seriously
restricts the transportability of a program, and the use of virtual memory
should only be considered if the problem warrants it.
.PP
The best approach for most applications is to restrict the memory
requirements of a program to the amount of per-process \fIphysical\fR
memory which one can reasonably expect to be available on a modern supermini
or supermicro.  An upper limit of one quarter of a megabyte is recommended
for most programs.  Programs which need all the memory they can get,
but which can dynamically adjust their buffer space to use whatever is
available, should use the \fBbegmem\fR system call to determine how
much memory is available in a system independent way.
.NH 2
make sure argument and function datatypes match
.PP
Compilers for the SPP and Fortran languages do not verify that a function
is declared correctly, or that a procedure or function is called with
the correct number and type of arguments.  This seriously compromises
the transportability of programs, because \fIwhether or not a type mismatch
causes a program to fail depends on the machine architecture\fR.
Thus, a program may work perfectly well on the software development
machine, but that does not indicate that the program is correct.
.PP
The most dangerous example of this is a procedure which expects an
argument of type short or char.  If passed an actual argument
of type integer, as happens when the actual argument is an integer
constant (i.e., NULL, 1, ('a'+10), etc.), we have a type mismatch since
the corresponding Fortran dummy argument is (usually) declared as
INTEGER\(**2, while the actual argument is of type INTEGER.
Whether or not the program will work on a particular machine depends
on how the machine arranges the bytes in an integer.  Thus, the
mismatch will go undetected on a VAX but the program will fail on
an IBM machine.
.PP
A similar problem occurs when a boolean dummy argument or function
is declared as an integer in the calling program, and vice versa.
In this case, whether or not the program works depends on what integer
values the compiler uses to represent the boolean constants \fBtrue\fR
and \fBfalse\fR.  The danger is particularly great if the compiler
happens to use the constants one and zero for true and false, since the
integer constants YES and NO are equivalent in value and similar in function.
.PP
The technique used by the Fortran compiler to implement subroutine and
function calls determines whether or not
\fBcalling a function as a subroutine\fR,
or calling a subprogram with the \fBwrong number of arguments\fR
will cause a program to fail.
For example, if the arguments to a subroutine are
placed on the hardware stack during a subroutine call, as is done by compilers
which permit recursive calls, then most likely the stack will not be
popped correctly upon exit from the subroutine, and the program will fail.
On a machine which statically allocates storage for argument lists,
the problem may go undetected.
.NH 2
do not use output arguments as local variables
.PP
This section is not directly relevant to the issue of portability,
but is included nonetheless because the topic presented here
is logically related to that discussed in the previous section.
.PP
The output or status arguments of a procedure should be regarded as
\fIwrite-only\fR.  Output arguments should not be used as local
variables, i.e., should not appear in expressions.
Likewise, the function value of a typed procedure should not be
used as a local variable.
.PP
To see why this is important, consider a procedure \fIalpha\fR 
with input arguments A and B, and output arguments C and D:
.DS
procedure alpha (a, b, c, d)
.DE
The calling program may not be interested in the return values C and D,
and may therefore call \fIalpha\fR as follows:
.DS
call alpha (a, b, junk, junk)
.DE
Since the SPP language passes arguments by reference, this call maps the
two dummy arguments C and D to the same physical storage location.
If C and D are used as distinct local variables within \fIalpha\fR
(presumably in an effort to save storage),
a subtle computation error will almost certainly result,
which may be quite difficult to diagnose.
.NH 2
avoid assumptions about the machine precision
.PP
The variation of numeric precision amongst machines by different manufacturers
is a well known problem affecting the portability of software.
This problem is especially important in numeric software, where 
the accumulation of errors may be critically important.
The SPP language addresses the problem of machine precision by providing
both single and double precision integer and floating point data types,
and by defining a minimum precision for each.
.PP
To produce a transportable program, one must select datatypes based on
the minimum precisions given in the table below.
The actual precision provided by the software development machine
may greatly exceed these values, but a program must not take advantage
of such excess precision if it is to be transportable.
In particular, a long integer should be used whenever a high precision
integer is required, and care should be taken to avoid large floating
point exponents.

.TS
center box;
cb s
c | c
lb | l.
Minimum Precision of Selected SPP Datatypes
=
datatype	precision
_
char	+/- 127 (8 bit signed)
short	+/- 32767 (16 bit signed)
int	+/- 32767 (16 bit signed)
long	+/- 2147483647 (32 bit signed)
real	6 decimal digits, exponent +/- 38
double	14 decimal digits, exponent +/- 38
.TE

.NH 2
do not compare floating point numbers for equality
.PP
In general, it is very difficult to reliably compare floating point
numbers for equality.  The result of such a comparison is not only
machine dependent, it is context dependent as well.
The only possible exception is when numbers are compared which have
only been copied in an assignment statement, without any form of type
coercion or other transformations.

.DS
.cs 1 22
real    x

begin
        x = 1.0D10
        if (x == 1.0D10)
            ...
end
.DE
.cs 1

.PP
The code fragment shown above, simple though it is, is machine dependent
because the double precision constant has been coerced to type real and
back to double by the time the comparison takes place.
Comparisons of just this sort are possible in IRAF programs which flag
bad pixels with the magic value \fBINDEF\fR.
Avoid type coercion of indefinites; use INDEF or INDEFR only for
type real pixels, INDEFD for type double pixels, and so on.
.PP
Occasionally it is necessary to determine if two floating point numbers are
equivalent to within the machine precision.
The predefined machine dependent constants \fBEPSILON\fR and
\fBEPSILOND\fR are provided in the SPP language to facilitate such comparisons.
The two single precision floating point numbers \fIx\fR and \fIy\fR are
said to be equivalent to within the machine precision,
\fIprovided the quantities \fRx\fI and \fRy\fI are normalized
to the range one to ten prior to comparison\fR,
if the following relation holds:
.DS
abs (x \(mi y) < EPSILON
.DE
.NH 2
use the standard predefined machine constants
.PP
A number of obviously machine dependent constants are predefined in the
SPP language.  These include such commonly used values as EPSILON, INDEF,
SZB\(ulCHAR, and so on.  Other less commonly used machine constants,
such as the maximum number of open files (LAST\(ulFD), are defined in
the system include file \fI<config.h>\fR.  Device dependent parameters such as
the block or sector size for a disk device are not necessarily unique
within a system, and are therefore not predefined constants.  A run time
call is required to obtain the value of such device dependent parameters.
.PP
A complete list of the standard predefined machine dependent constants
is shown below.  Some of these are difficult to use in a transportable fashion.
The transportability of a program is greatest when no machine dependent
parameters are used, be they formally parameterized or not.

.TS
center box;
cb s s
ci | ci | ci
l | c | l.
Machine Dependent Constants
=
name	datatype	meaning
_
BYTE\(ulSWAP	i	swap magtape bytes?
EPSILON	r	single precision machine epsilon
EPSILOND	d	double precision machine epsilon
INDEF	r	indefinite pixel of type real
INDEF\fIt\fR	\fIt\fR	indefinite valued pixels
MAX\(ulDIGITS 	i	max digits in a number
MAX\(ulEXPONENT	i	largest floating point exponent
MAX\(ulINT	i	largest positive integer
MAX\(ulLONG	l	largest positive long integer
MAX\(ulREAL	r	largest floating point number
MAX\(ulSHORT	i	largest short integer
NBITS\(ulINT	i	number of bits in an integer	
NBITS\(ulSHORT	i	number of bits in a short integer
NDIGITS\(ulDP 	i	number of digits of precision (double)
NDIGITS\(ulRP	i	number of digits of real precision
SZB\(ulADDR	i	machine bytes per address increment
SZB\(ulCHAR	i	machine bytes per char
SZ\(ulFNAME	i	max chars in a file name
SZ\(ulLINE	i	max chars in a line
SZ\(ulPATHNAME	i	max chars in OS dependent file names
SZ\(ulVMPAGE	i	page size, chars (1 if no virtual mem.)
SZ\(ul\fItype\fR	i	sizes of the primitive types
WORD\(ulSWAP	i	swap magtape words?
.TE

.NH 2
explicitly initialize variables
.PP
Storage is statically allocated for all local and global variables 
in the SPP language.  Unless explicitly initialized, the initial value
of a variable is \fIundefined\fR.  Although many compilers implicitly
initialize variables with the value zero, this fact is quite machine
dependent and should not be depended upon.  Local variables should be
explicitly initialized in an assignment or \fBdata\fR statement before
use.
.PP
Global variables (in common blocks) cannot be initialized with
the \fBdata\fR statement.  Some compilers permit such initialization,
but this feature is again quite machine dependent, and should not
be depended upon.  Global variables must be initialized by a run
time initialization procedure.
.NH 2
beware of functions with side effects
.PP
The order of evaluation of an expression is not defined.  In particular,
the compiler may evaluate the components of a boolean expression in
any order, and parts of a boolean expression may not be evaluated at
all if the value of the expression can be determined by what has already
been evaluated.
This fact can cause subtle, potentially machine dependent problems
when a boolean expression calls a function with side effects.
To see why this is a problem, consider the following example:
.DS
.cs 1 22
if (flag || getc (fd, ch) == EOF)
    ...
.DE
.cs 1
.PP
The function \fIgetc\fR used in the example above has two side effects:
it sets the value of the external variable \fIch\fR, and it advances the
i/o pointer for file \fIfd\fR by one character.
If the value of \fIflag\fR in the \fBif\fR statement is true,
the value of the boolean expression is necessarily true, and the compiler
is permitted to generate code which would skip the call to \fIgetc\fR.
Whether or not \fIgetc\fR gets called during the evaluation of this expression
depends on how clever the compiler is (which cannot be predicted),
and on the run-time value of the variable \fIflag\fR.  
.NH 2
use of intrinsic functions
.PP
The intrinsic functions are generic functions, meaning that the same
function name may be used regardless of the datatype of the arguments.
Unlike ordinary external functions and local variables,
\fIintrinsic functions should not be declared\fR.  Not all compilers
ignore intrinsic function declarations.
.PP
Only the intrinsic functions shown in the table below should be used in SPP
programs.  Although current compilers for the SPP language will accept
many Fortran intrinsic functions other than those shown, the use of such
functions is nonstandard, and will not be supported by future compilers.

.TS
center box;
cb s s s s s s
l l l l l l l.
Standard SPP Intrinsic Functions
=
abs	atan	conjg	exp	long	nint	sinh
acos	atan2	cos	int	max	real	sqrt
aimag	char	cosh	log	min	short	tan
asin	complex	double	log10	mod	sin	tanh
.TE

.PP
Note that the names of the type coercion functions (\fBchar\fR, \fBshort\fR,
\fBint\fR, \fBreal\fR, etc.) are the same as the names of the datatypes in
declarations.  The functions \fBlog10\fR, \fBtan\fR, and the hyperbolic
functions, may not be called with complex arguments.
.NH 2
explicitly align objects in global common
.PP
Care should be taken to align objects in common blocks on word boundaries.
Since the size of a word is machine dependent, this is not always easy
to do.  Common blocks which contain only objects of type integer and
real are the most portable.  Avoid booleans in common blocks;
use integer variables with the values YES and NO instead.
Objects of type char and short should be grouped together,
preferably at the end of the common block, with the total size of the
group being an even number.  Remember that the SPP compiler allocates
one extra character of storage for character arrays; character arrays
should therefore be odd-dimensioned.

.NH 1
Software Documentation
.PP
Even the best software system is of no value unless people use it.
Given several software packages of roughly similar capabilities, 
people are most likely to use the package which is easiest to understand,
i.e., which has the simplest interface, and which is best documented.
Documentation is perhaps the single most important part of the user interface
to a system, and to a large extent the quality of the documentation for
a system will determine what judgment people make of the quality of the
system itself.
.PP
The documentation associated with a large software system (or applications
package) can be classed as either user documentation or system documentation.
User documentation describes the function of the modules making up the
system, without reference to the details of how the modules are implemented.
System documentation includes design documentation,
documentation describing the details of how the software is implemented,
and documentation describing how to install and test the system.
.NH 2
User Documentation
.PP
The first contact a user has with a system is usually provided by the
user documentation for the system.  Good user documentation should provide
an accurate and concise introduction to the system; it should not emphasize
the glamorous system features or otherwise try to "sell" the system.
It should not be necessary for the user to read all the documentation to
be able to make simple use of the system.  The documentation should be
structured in such a way that the user may read it to the level of detail
appropriate to his or her needs.  Good user documentation is characterized by 
its conciseness and clarity, not by the sheer volume of documentation provided.
.PP
In what follows, we use the terms "system", "subsystem", and "package"
interchangeably.  The term "function" refers both to CL callable tasks
and to library procedures.  The term "user" refers both to end users and
to programmers, depending on the nature of the system or package to be
documented.  The term "document" need not refer to separately bound
documents; whether separate documents or multiple sections within a
single document are produced depends upon the size of the system and
upon the number of authors.
.PP
The user documentation for a large system or package should consist of at
least the following documents:
.RS
.IP (1)
The \fBUser's Guide\fR, which introduces the user to the system,
and provides a good overall summary of the facilities provided by the system.
This document should provide just enough information to tell the
first time user how to exercise the most commonly used functions.
Great care should be taken to produce a highly readable document,
minimizing technical jargon without sacrificing clarity and conciseness.
Plenty of figures, tables, and examples should be included to enhance
readability.
.IP (2)
The \fBReference Manual\fR, which describes in detail the facilities
available to the user, and how to use these facilities.  The reference
manual is the definitive document for the system.  It should be complete
and accurate; technical terms and formal notations may be used for
maximum precision and clarity.  The reference manual defines the \fIuser
interface\fR to the system; implementation details do not belong here.
.RE
.PP
The minimum reference manual consists of a set of so-called \fBmanual
pages\fR, each of which describes in detail one of the functions provided
by the system.  The manual pages should be available both on-line and
in printed form.  The printed reference manual should contain any
additional information which pertains to more than one function, and
which therefore does not belong in a manual page, but which is too
technical or detailed for the user's guide.
.PP
Other user documentation might include a report of the results of any
tests of the system, as when an a scientific analysis package is tested
with artificial data.  An objective evaluation of strengths and shortcomings
of the algorithms used by the package might be useful.
It is important that both the user and the implementor understand the
limitations of the software, and its intended range of application.
.NH 2
System Documentation
.PP
System documentation is required to produce, maintain, test, and install
software systems.  The main requirement for system documentation is
that it be accurate; it need not be especially well written, is usually
quite technical, and need not be carefully typeset nor printed.
The system documentation for a package should be maintained in files in
the source directories for the package which it describes.
.PP
The system documentation for a large system or package should include
the following documents:
.RS
.IP (1)
The requirements for the system.
.IP (2)
The detailed technical specifications for the system.
.IP (3)
For each program in the system, a description of how that program is
decomposed into modules (i.e., a structure chart), and the function
of each module.
.IP (4)
Implementation details, including descriptions of the major data structures
and details of their usage, descriptions of complicated algorithms, 
important strategies and design decisions, and notes on any code
that might be hard for another programmer to understand.  This need not
extend to describing program actions which are already documented
using comments in the code.
.IP (5)
A test plan, describing what verification software is available,
how to use it, and how to interpret the results.  The amount of
documentation required should be minimized by automating the verification
software as much as possible.
.IP (6)
Instructions on how to install the system when it is ported to a new
computer.  List any include files which may need to be edited,
directories required by the system which may have to be created,
libraries or other program modules external to the package which
are required, and any file or device names which may have to be changed.
A description of how to compile each program should be included;
a UNIX \fIMakefile\fR for the package would be ideal.
.IP (7)
A revision history for the software, giving the names of the original
authors, the dates of the first release and of all subsequent revisions,
and a summary of the changes made in each release of the system.
Any bugs, restrictions, or planned improvements should be noted.
.RE
.PP
These documents are listed more or less in the order in which they would
be produced.  The requirements and specifications of a system are written
during the preliminary design phase.
Documentation describing the decomposition of programs into modules,
and detailing the data structures and algorithms used by the package
is written during the detailed design stage.
After the code has been written and tested,
additional notes on the details of the implementation should be made,
and the original design documentation should be brought up to date.
The remaining documentation should be produced after implementation,
before the package is first released.
.NH 2
Documentation Standards
.PP
All documentation should be maintained in computer readable form on the
software development machine.  The standard text processing software
for IRAF user documentation is the UNIX \fITroff\fR text formatter, used
with the \fIms\fR macros, the \fITbl\fR table preprocessor, the \fIEqn\fR
preprocessor for mathematical graphics, and so on.  Associated utilities
such as \fISpell\fR and \fIDiction\fR are useful for detecting spelling
errors and bad grammatical constructs.  User documentation will be
typeset and reproduced in quantity by the KPNO print shop.
.PP
The standard text processing software for all on-line manual pages and
system documentation is the \fILroff\fR text formatter, a portable
IRAF system utility.  The UNIX utilities cannot be used for on-line
documentation, and should not be used for system documentation because
it is difficult to justify the expense of typesetting system documentation,
and because system documentation is not maintained in printed form,
and many users will not have access to the UNIX text processing tools.
The Lroff text processor is more than adequate for most system
documentation.
.PP
The format of user documentation should be similar to that used in this
document, i.e.:
.RS
.IP (1)
The title page should come first, consisting of the title,
the names of the authors and of their home institutions, an abstract
summarizing the contents of the document, and the date of the first
release of the document, and of the current revision.
.IP (2)
A table of contents for the document should be given next,
except possibly in the case of very small documents.
.IP (3)
Next should come the introduction, followed by the body of the document,
organized into sections numbered as in this document.
.IP (4)
Any references, appendices, large examples, or the index or glossary
if any, should be given last.
.RE
.PP
Lroff and Troff format source files should have the extensions ".hlp"
and ".ms", respectively.  \fIAll documentation for a package should
be maintained in the source directories for the package\fR,
to ensure that the documentation gets distributed with the package,
does not get lost, can easily be found, and to make it easier for the
programmer to keep the documentation up to date.
.NH 2
Technical Writing
.PP
Technical writing is a craft comparable in difficulty to computer programming.
Writing good documentation is not easy, nor is it a single stage process.
Documents must be designed, written, read, criticized, and then rewritten
until a satisfactory document is produced.  The process has much in common
with programming; first one should establish the requirements or scope of the
document, then one should prepare an initial outline (design), which is 
successively refined until it is detailed enough to fully define the contents
of the final document.  Writing should not begin until one has structured
the document into a hierarchy of sections, each of which is well named,
and each of which documents a single topic.
.PP
English is not a formal language, like a computer language, and it is
accordingly very difficult to define a standard style for technical prose.
A discussion of writing style in general is given in the excellent little
book by Strunk and White [14].  Technical writing differs from other writing
in that the material should be clearly and logically organized into sections,
and graphics, i.e., lists, tables, figures, examples, etc., should be
liberally used to present the material.  Large, monolithic paragraphs,
or entire pages containing only paragraphs of text, appear forbidding to
the reader and should be avoided.
.PP
The following guidelines for writing style in technical documents are
reproduced from reference [8], \fISoftware Engineering\fR by I. Sommerville:
.RS
.IP (1)
Use active rather than passive tenses when writing instruction manuals.
.IP (2)
Do not use long sentences which present a number of different facts.
It is much better to use a number of shorter sentences.
.IP (3)
Do not refer to previously presented information by some reference
number on its own.  Instead, give the reference number and remind the
reader what the reference covered.
.IP (4)
Itemize facts wherever possible rather than present them in the form
of a sentence.
.IP (5)
If a description is complex, repeat yourself, presenting two or more
differently phrased descriptions of the same thing.  If the reader
fails to completely understand one description, he may benefit from having
the same thing said in a different way.
.IP (6)
Don't be verbose.  If you can say something in 5 words do so, rather than
use ten words so that the description might seem more profound.  There is
no merit in quantity of documentation \(em quality is much more important.
.IP (7)
Be precise and, if necessary, define the terms which you use.
Computing terminology is very fluid and many terms have more than one
meaning.  Therefore, if such terms (such as module or process) are used,
make sure that your definition is clear.
.IP (8)
Keep paragraphs short.  As a general rule, no paragraph should be made
up of more than seven sentences.  This is because of short term memory
limitations.  [Another general rule is that few paragraphs should be
longer than seven or eight \fIlines\fR on an 8\(12 by 11 inch page.]
.IP (9)
Make use of headings and subheadings.  Always ensure that a consistent
numbering convention is used for these.
.IP (10)
Use grammatically correct constructs and spell words correctly.
Avoid constructs such as split infinitives.
.RE
.PP
Technical writing should not be regarded as a chore.  The process is difficult
and challenging, and can be quite rewarding.  Often the act of writing
results in new insight for the writer.  Writing is a form of judgment;
if an idea or design cannot be explained clearly, there is probably something
wrong with it.  Writing forces one to consider an issue in detail, and often
is the source of new ideas.  A software system cannot be widely used until
it is documented, and the quality of the documentation will do much to
ensure the success of the system itself.

.sp 2
.ps -1
.vs -1p
.pg
.ftB
References
.sp.4
.pg
.ta .3i
.in .3i
.ftR
.ti0
1.	D. C. Wells and E. W. Greisen,
.ul
FITS \(em A Flexible Image Transport System,
Proceedings of the International Workshop on Image Processing in
Astronomy, Ed. G.Sedmak, M.Capaccioli, R.J.Allen, Osservatorio
Astronomico di Trieste, 1979.
.sp.4
.ti0
2.	E. Allman and M. Stonebreaker,
"Observations on the Evolution of a Software System",
\fIComputer\fR, June 1982.
.sp.4
.ti0
3.	B. W. Kernighan and D. M. Ritchie,
.ul
The C Programming Language,
Prentice - Hall, Inc., Englewood Cliffs, New Jersey, 1978.
.sp.4
.ti0
4.	H. Spencer et al.,
.ul
Indian Hill C Style and Coding Standards as amended for U of T Zoology UNIX.
An annotated version of the original Indian Hill (Bell Labs) style manual for
the C language.
.sp.4
.ti0
5.	D. Tody,
.ul
A Reference Manual for the IRAF Subset Preprocessor Language,
KNPO, January 1983.
.sp.4
.ti0
6.	American National Standards Institute, Inc.,
.ul
American National Standard Programming Language Fortran,
document number ANSI X3.9-1978, April 1978.
.sp.4
.ti0
7.	J. Larmouth,
.ul
Fortran 77 Portability,
Software \(em Practice and Experience, Vol. 11, 1071-1117 (1981).
.sp.4
.ti0
8.	I. Sommerville,
.ul
Software Engineering,
Addison-Wesley, 1982.
.sp.4
.ti0
9.	W. P. Stevens,
.ul
Using Structured Design,
John Wiley & Sons, Inc., 1981.
.sp.4
.ti0
10.	J. D. Aron,
.ul
The Program Development Process; Part II, The Programming Team,
Addison-Wesley, 1983.
.sp.4
.ti0
11.	W. S. Davis,
.ul
Tools and Techniques for Structured Systems Analysis and Design,
Addison-Wesley, 1983.
.sp.4
.ti0
12.	B. Meyer,
"Principles of Package Design",
\fICommunications of the ACM\fR, July 1982, Vol. 25, No. 7.
.sp.4
.ti0
13.	G. D. Bergland,
"A Guided Tour of Program Design Methodologies,"
\fIComputer\fR, October 1981.
.ti0
14.	W. Strunk Jr. and E. B. White,
.ul
The Elements of Style,
Mcmillan Publishing Co., Inc., 1979 (third edition).