Suggested guidelines

Here are the present guidelines for writing code:

• Code should be transportable across machines small and big. We would like the same source code to serve for both single-processor Linux PCs and for clusters of Apple Xserve G5 machines, to pick an example. As an example, we might choose to have a wrapper subroutine for FFT routines that decides at compile or even run time to call the FFTW routine if on a single-processor computer, or the Apple dist_fft library if on an Apple cluster.

  This also means we should try to use languages that are widely available and understood. Basic C++ code fits this goal pretty well.

• We should use fairly long and descriptive names for routines and variables. It's easy to understand at a glance what's going on with a routine like
  dm_array_math.apply_support_constraint( complexarr array, supportarr support, float beta).

• We should identify authorship of routines, and document changes, in the .cpp files. For example, we might have a class dm_array_math which might have one routine written by person A, and another by person B. Each routine within this class should have something in it like

  // 15-aug-2005: original program written by Daffy Duck.
  // 16-aug-2005: modified by Tweety Bird to handle both single
  //   and double precision.
  

• Data files should be transportable across machines. We will want all our files to have a byte at the beginning that says if they are in big-endian or little-endian order; it would likely be good to have this match the byte order on the machine that's doing the most work.

  It's also useful to have a byte that records the file version so that if additional information needs to be added later on

• Heavy lifting should be done by compiled code. IDL is nice for examining and evaluating data files, but iterative calculations, and assembly of multiple 2D files into a 3D diffraction data set, represent jobs that are best left to compiled code that can be run on a cluster machine if available.

• Self-documenting scripts are nice. Driving calculations by using some kind of script language text file means that you can document how a particular calculation was done.