1.3.2.1 A sample include file

Here is `damped.i', which defines the damped sine wave functions we've been designing in this chapter:

/* damped.i */ local damped; /* DOCUMENT damped.i --- compute and output damped sine waves SEE ALSO: damped_wave, q_out */ func damped_wave(phase, Q) /* DOCUMENT damped_wave(phase, Q) returns a damped sine wave evaluated at PHASE, for quality factor Q. (High Q means little damping.) The PHASE is 2*pi after one period of the natural frequency of the oscillator. PHASE and Q must be conformable arrays. SEE ALSO: q_out */ { nu = 0.5/Q; omega = sqrt(1.-nu*nu); return sin(omega*phase)*exp(-nu*phase); /* always zero at phase==0 */ } func q_out(Q, file) /* DOCUMENT q_out, Q, file or q_out(Q, file) Write the damped sine wave of quality factor Q to the FILE. FILE may be either a filename, to create the file, or a file object returned by an earlier create or q_out operation. If q_out is invoked as a function, it returns the file object. The external variable theta determines the phase points at which the damped sine wave is evaluated; q_out will write two header lines, followed by two columns, with one line for each element of the theta array. The first column is theta; the second is damped_wave(theta, Q). If Q is an array, the two header lines and two columns will be repeated for each element of Q. SEE ALSO: damped_wave */ { if (structof(file)==string) file = create(file); n = numberof(Q); for (i=1 ; i<=n ; ++i) { /* loop on elements of Q */ write, file, "Q = "+pr1(Q(i)); write, file, " theta amplitude"; write, file, theta, damped_wave(theta,Q(i)); } return file; }

You would type

#include "damped.i"

to read the Yorick statements in the file. The first thing you notice is that there are comments -- the text enclosed by /* */. If you take the trouble to save a program in an include file, you will be wise to make notes about what it's for and annotations of obscure statements which might confuse you later. Writing good comments is arguably the most difficult skill in programming. Practice it diligently.