#### 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.