• Document the program. Computer programs can be almost
useless without adequate documentation. Stonehenge has been
described as “the world’s largest undocumented computer
system.” 3 Failure to document is often justified by the assumption that the program will not be used again. This rationalization is self-fulfilling, because even the author may find an
undocumented program difficult to reuse once the details are
forgotten.
Documentation should state the program’s goals and
method. The input and output variables, their units, and how
they are defined should be listed. Implicit assumptions and
restrictions are worth noting. Comments should identify major
portions of the program and describe their functions.
Documentation is best written when writing a program
because it can aid in debugging. Moreover, once a program is
fully written, it is harder to remember how it works. Documentation included in the program is less prone to be lost than that
written separately.
Finally, documentation helps scientists exchange programs
and work in collaboration. This can be useful, except in the
apocryphal cases of programmers writing gigantic undocumented programs to maximize their job security.
• Use modular programming. Large programs can generally
be divided into smaller subroutines or functions, which can
be used like the functions (e.g., sine, square root) supplied by
many computer languages. Each subroutine can be tested separately and then used in various programs. Subroutines can
handle applications that frequently recur, such as reading or
plotting data or carrying out a mathematical operation. This
approach saves the time needed to write and debug portions of
a program similar to one already available. Moreover, the
overall structure of a program containing a set of calls to subroutines is generally easier to understand, because many complexities are isolated into subroutines.
• Make programs comprehensible. It is helpful to be able to
understand programs once written. Clear documentation and
modular programming help. In addition, it should be easy to
tell what portions will be executed under which circumstances.
For this purpose, portions of a program should be executed
sequentially, rather than jumping backwards and forwards
within a program.
Similarly, the statements themselves can be written clearly.
The use of mnemonic variable names and natural groupings of
variables can help. For example, it is somewhat unclear that
X = 0.23873 * A / (Y * Y * Y)
gives the average density X of a planet with mass A and radius
Y, whereas
RHO = AMASS / ((4.0/3.0) * PI * (RADIUS**3))
Fig. A.8-3 Structure of the loops for the string synthetic seismogram
calculation.
A.8 Scientific programming 469
C OUTER LOOP OVER MODES
DO 10 N = 1, NMODE
terms for each mode
that do not depend on time
C INNER LOOP OVER TIME STEPS
DO 15 J = 1, NTSTEP
terms that depend on time
C COMPUTE DISPLACEMENT
15
CONTINUE
10
CONTINUE
2 Kernighan and Plauger (1978).
shows how it was computed. This helps avoid the common
situation where, given a large collection of computer output,
cases are rerun because it is unclear what parameters were
used. Moreover, subsequent “improved” versions of the program can be checked to see whether they give the same results.
• The program is somewhat efficient. Some thought is generally put into optimizing scientific programs to make them run
rapidly. The program could find the displacement by looping
over time and summing all the modes at each time step. However, consideration of the equation shows that three terms,
sin (nπx/l), sin (nπx s /l), and exp [−(ω n τ) 2 /4] are evaluated only
once for each mode, whereas only cos (ω n t) is evaluated for
each time step. It is thus more efficient to loop over the modes
and evaluate each at all times (Fig. A.8-3). Because the outer
(mode) loop is executed 200 times, whereas the inner (time)
loop is executed 200 × 50 = 10,000 times, the inner loop should
be as efficient as possible. The program would run more slowly
if the loops were reversed. The difference, though not significant for this calculation, might be significant for much larger
numbers of time steps and modes.
Further improvements could be made to fully optimize the
program. Optimization is not an end in itself, because the
programmer’s time and the intelligibility of the program are
also important. Programmers typically try to write reasonably optimized programs without making them impossible to
understand and debug. Once fully tested, a program that will
be used heavily may be worth further optimization if the computer time savings justify the effort required. There is no point
in “getting the wrong answer as fast as possible.” 2 Certain
computers, such as those using parallel processors, may require
specialized optimization.
A.8.2 Programming style
The style in which programs are written can make them easier
to develop, debug and use. A few suggestions, though not absolute rules, may be useful.
3 Brooks (1975).
useless without adequate documentation. Stonehenge has been
described as “the world’s largest undocumented computer
system.” 3 Failure to document is often justified by the assumption that the program will not be used again. This rationalization is self-fulfilling, because even the author may find an
undocumented program difficult to reuse once the details are
forgotten.
Documentation should state the program’s goals and
method. The input and output variables, their units, and how
they are defined should be listed. Implicit assumptions and
restrictions are worth noting. Comments should identify major
portions of the program and describe their functions.
Documentation is best written when writing a program
because it can aid in debugging. Moreover, once a program is
fully written, it is harder to remember how it works. Documentation included in the program is less prone to be lost than that
written separately.
Finally, documentation helps scientists exchange programs
and work in collaboration. This can be useful, except in the
apocryphal cases of programmers writing gigantic undocumented programs to maximize their job security.
• Use modular programming. Large programs can generally
be divided into smaller subroutines or functions, which can
be used like the functions (e.g., sine, square root) supplied by
many computer languages. Each subroutine can be tested separately and then used in various programs. Subroutines can
handle applications that frequently recur, such as reading or
plotting data or carrying out a mathematical operation. This
approach saves the time needed to write and debug portions of
a program similar to one already available. Moreover, the
overall structure of a program containing a set of calls to subroutines is generally easier to understand, because many complexities are isolated into subroutines.
• Make programs comprehensible. It is helpful to be able to
understand programs once written. Clear documentation and
modular programming help. In addition, it should be easy to
tell what portions will be executed under which circumstances.
For this purpose, portions of a program should be executed
sequentially, rather than jumping backwards and forwards
within a program.
Similarly, the statements themselves can be written clearly.
The use of mnemonic variable names and natural groupings of
variables can help. For example, it is somewhat unclear that
X = 0.23873 * A / (Y * Y * Y)
gives the average density X of a planet with mass A and radius
Y, whereas
RHO = AMASS / ((4.0/3.0) * PI * (RADIUS**3))
Fig. A.8-3 Structure of the loops for the string synthetic seismogram
calculation.
A.8 Scientific programming 469
C OUTER LOOP OVER MODES
DO 10 N = 1, NMODE
terms for each mode
that do not depend on time
C INNER LOOP OVER TIME STEPS
DO 15 J = 1, NTSTEP
terms that depend on time
C COMPUTE DISPLACEMENT
15
CONTINUE
10
CONTINUE
2 Kernighan and Plauger (1978).
shows how it was computed. This helps avoid the common
situation where, given a large collection of computer output,
cases are rerun because it is unclear what parameters were
used. Moreover, subsequent “improved” versions of the program can be checked to see whether they give the same results.
• The program is somewhat efficient. Some thought is generally put into optimizing scientific programs to make them run
rapidly. The program could find the displacement by looping
over time and summing all the modes at each time step. However, consideration of the equation shows that three terms,
sin (nπx/l), sin (nπx s /l), and exp [−(ω n τ) 2 /4] are evaluated only
once for each mode, whereas only cos (ω n t) is evaluated for
each time step. It is thus more efficient to loop over the modes
and evaluate each at all times (Fig. A.8-3). Because the outer
(mode) loop is executed 200 times, whereas the inner (time)
loop is executed 200 × 50 = 10,000 times, the inner loop should
be as efficient as possible. The program would run more slowly
if the loops were reversed. The difference, though not significant for this calculation, might be significant for much larger
numbers of time steps and modes.
Further improvements could be made to fully optimize the
program. Optimization is not an end in itself, because the
programmer’s time and the intelligibility of the program are
also important. Programmers typically try to write reasonably optimized programs without making them impossible to
understand and debug. Once fully tested, a program that will
be used heavily may be worth further optimization if the computer time savings justify the effort required. There is no point
in “getting the wrong answer as fast as possible.” 2 Certain
computers, such as those using parallel processors, may require
specialized optimization.
A.8.2 Programming style
The style in which programs are written can make them easier
to develop, debug and use. A few suggestions, though not absolute rules, may be useful.
3 Brooks (1975).