Coding How To

To see the things that need to be done, first consult the Coding To Do page.

Sections of code that require urgent attention have a *** next to them so as to be able to search for them easily. If it is urgent enough to require that it be fixed before running, do not put it in a comment so it will screw up the compilation, and make you deal with it (hopefully not by just commenting it out).

Loose Coding Conventions

Fashions change, but for the time being, this is the preferred coding style. Of course, consult the actual source code for real examples.

Each source file should have the GNU LGPL indicator.

Comments are Doxygen style with //! for brief comments and for other comment blocks use:

/*! Blah blah 
 */

These comments are all in the source files, not the header files. Any comments in the headers are intended to stay in the headers upon distribution, and generally should be // comments, not /* ... * /. The // style I find much easier to spot and see what's what.

Global functions and variables are all lower case. Global functions are encouraged to have underscores just to have something to make them stand out (like matrix m_times_m(double *m1,double *m2,double *ans) rather than somethingLikeThis.

Publically accessible member functions have word starts capitalized (ThisIsAnExample). Protected/private member functions generally lowercase, optionally with rest capitalized (thisIsAnExample). Member functions shouldn't have underscores, unless it is a function common to many classes, like dump_in_atts(), which is found in all the interface data classes.

Defines are all caps and underscores.

Enums have an inital capital sequence, then lower cases, such as BLAH_Blah_blah.

Usually have tabwidth=4 spaces.

Any printf, cout/cerr or other purely debugging related code should be on lines like '[whitespace]DBG the code'. Toward the beginning of the file, define DBG to be nothing. Each DBG line can be commented out and uncommented with the hidegarbage utility in the lax directory. This is to make it easy to remove all the cerr garbage for a release. If someone knows how to achieve the same thing with pure defines, let me know.

Example:

 --- the gnu lgpl snippet goes here ---
/********* blah.cc *********/

#define DBG

enum Something {
    SOME_Thing,
    SOME_Thing_Else
};

//! Doxygen brief comment
/*! Doxygen long comment
 * comment block cont.
 */
 // Persistent comments 
 // go here with one space before the //.
 // /**/ blocks are usually avoided.
void Blah(blah *blah,blah blah)
{
    for (c=0; c<blah; c++) {
        blah();
    } 
    if (1) {
        blah();
    } else {
    }
}

//------------------------------- Blah -----------------------

void Blah::Blah()
{
    blah=BLAH_BLAH;
}

blah.h:

 --- the gnu lgpl snippet goes here ---
#ifndef BLAH_H
#define BLAH_H

//------------------------------- Blah -----------------------
 // Blahb alablbal abalhb al
class Blah
{
    int blah; // blah blah
    Blah();
};

#endif