Standards

For information relating to POSIX, the POSIX Programmers Guide may be of assistance. Information on the POSIX committee (also known as the IEEE PASC Committee) is available here while the official PASC page may also be helpful.

Layout

for(int outer=0; outer < 30; outer++)
{
    ....
    for(int middle=0; middle < 20; middle++)
    {
    	.... 
	for(int inner=0; inner < 10; inner++)
	{
	    ....
	    code to do things
	    ....
	}
    }
} 

whereas something like this:

for(int outer=0; outer < 30; outer++;) {
    ....
    for(int middle=0; middle < 20; middle++) {
    	.... 
        for(int inner=0; inner < 10; inner++) {     
            ....
            code to do things
            ....
        }                                   
    }       
}         

while fine for the compiler is more difficult to follow.

Documentation

Comments

Any code written must be commented such that that:

• names and roles of variables, classes, funtions, etc are described, optimally when they are first encountered.
• comments are short but succint ; volumes of prose are not required !
• contributors who have not previously seen the code can understand how it works and how it is to be used.

Header Files

	molecule.h
	my_header.h
	atom.revision_1.h

The following are not valid filenames for header files:

	molecule.hpp
	my_header.hxx
	atom.revision_1. (i.e. no extension !)
	molecule.c
	molecule.cpp
	molecule.cxx

Header files may contain the following elements, examples of which are given.

Lexical Element	Example of Code	Notes/Comments
Type Definitions	typedef float REAL	Define a type REAL which is a floating-point number
Templates	List<Atom> *resatomlist;	Example of class data using templates
Function Declarations	Atom *GetAtom(Atom *atom);	A class member function declaration
Inline Function Declarations	char *GetResidueName() {return residuename;}	An access function for class Residue
Data declarations	empty	empty
Constant Definitions	e.g. const float pi = 3.14159;	The keyword const redefines the word pi to mean a floating-point number whose value is set to 3.14159
Enumerations	e.g. enum colour(red, green, blue}; colour c;	Thus, we could specify: c=green; to set the colour
Name declarations	empty	empty
Include directives	#include "Molecule.h"	the quotes indicate a user-defined header file is to be included.
Comments	// This is a comment line	The C++ comment characters (//) should be used in preference over the old style (/* and */) comment characters.

Header files may not contain:

• Ordinary function definitions, i.e. definitions typically found in the corresponding .cpp file
• Data definitions, e.g. instances of variable definitions/declarations
• Constant aggregate definitions

Header files will define and test a preprocessor variable X_H preventing multiple inclusion of that header file in the same translation unit:

	#if !defined(RESIDUE_H)
	#define RESIDUE_H

	...rest of code...

	#endif

Each header file will contain #include statements for all header files on which it depends:

	#include "header_file.h"

or

	#include 

for default (compiler-default) header files.

Implementation Files

	residue.cpp
	atom.v2r1.cpp
	molecule_trial_version.cpp

By contrast, all the following are NOT valid filename:

	residue.c
	atom.cxx
	molecule.c.v1.2
	atom_trial_version.c
	my_class.cc

They may contain the following:

Method Definitions	example in here !!!!!
Static class member definitions	example in here !!!!!

They may not contain variables in global scope (function or class scope only).

Names

Item	Example(s)
Names of templates/classes/functions to start with an uppercase letter	Store<Atom>, class Atom, GetResname()
unless they are standard library extensions	inverse_cholesky, numeric_vector
Only use abbreviations when they are obvious	For example, GetResName is OK, but NoAtoms is too unclear !
Words within a name should start with an uppercase letter	For example, AddtoResidue and GetNextAtom are both OK.
The first letter of Variable and data names should be lowercase	firstAtom, nextProtein, atom, *molecule are all OK

Preprocessor statements

#define REAL float

Instead, the keyword typedef should be employed. Thus, the above example may be correctly written as:

	typedef	float REAL;

Classes

        Atom()                          // constructor for new atom
        virtual ~Atom(void) {}          // destructor
        Atom(const &Atom old_atom);     // copy constructor

Note the use of the keyword virtual. This instructs C++ to call the destructor of the derived class and then [if required] that of the base class.

Class data members should be explicitly declared to be private by using the private keyword:

class Atom
{
private:
        REAL            x,y,z;                  // separate coords
        vector          xyz;                    // coords as vector
        string          symbol;                 // atomic symbol
...
rest_of_code
....
};

The default mode of access protection is private, however, stating this explicitly in the code removes one further source of potential confusion.

Methods and Functions

...
        static const float atomicMass;
...

The parameter will be initialised within some derived class. Note that the additional parameter static acts to limit the scope of the variable to the class.

Booleans and Strings

        bool flag = false;

The Standard Library defines the string type which should be used rather than the older char type.So, for example:

        char    symbol[3];

becomes:

        string  symbol;

This allows for more flexible string handling.

Casting

Thus, C-style casting such as:

        float angle;
        (double)angle = sin(45);        // forces angle to be treated
                                        // as a double

should not be employed at all !

Libraries

Any questions and bug reports to Mark Williams. This page was last updated on 19th June 2005