Notes about coding

As mentioned above, the marching orders for code development laid out in the LAL-Spec are often quite general. The purpose of this chapter is try to record the collective interpretation of the LAL-Spec so that we can consistently apply it.

Use of MACROS: The LAL-Spec says ``macros'' are deprecated. What the hell does that mean? The interpretation we are using clearly captures the intent. There are a number of macros for common use in the std LAL files, but these under strict control of the librarian. In your modules (.c files), you may use macros to replace small snippets of code. However because header files may be included in other code, you should not use macros in your .h files.

If you have a ``#define SomeMacro'' that needs to be included in many different files, it probably belongs in the LALConstant.h file or one of the other /lal/std/include files. Please contact the Librarian.

Defining the RCS ID string: The LAL-Spec requires all header, module and test files to define the RCS ID String with the following macro:

          NRCSID(LALTEMPLATEH,"$Id: lsd.tex,v 1.41 2003/06/10 20:43:48 jolien Exp $");

The reason we assign the Id with this macro is that without it, the compiler prints annoying warning messages. Note this macro is an example of one macros for ``common use'' described above.

Error Codes and Messages: The LAL-Spec discusses the statuscode and statusDesription, i.e. the error codes and messages returned by a LAL function. Here we solidify the name space convention. These should be hash-defined in the header file, e.g. in MyHeader.h we would have

/* <lalErrTable file="MyHeaderHErrorTable"> */

#define MYHEADERH_ENUL  1 
#define MYHEADERH_EOUT  2
#define MYHEADERH_EDIV  3

#define MYHEADERH_MSGENUL  "Null pointer"
#define MYHEADERH_MSGEOUT  "Output already exists"
#define MYHEADERH_MSGEDIV  "Division by zero"

/* </lalErrTable> */

The names should begin with the file name and extension (h) all converted to upper case. The error codes are followed by _E$<$name$>$. The error messages are followed by _MSGE$<$name$>$.

The $<>$ed key-words shown before and after the codes are the key-words for automatic documentation system. You must use these to automate the inclusion of the error codes in the documentation. More on this later.