[Box Backup] Coding standards

[Ben Summers]

In preparation for getting the code up for others to work on, I've  
written some notes on coding standards. I hope this documents the  
style and preferences to date, and that I haven't forgotten anything.

I think that consistency is important, and since the code base is  
quite large, we should stick to the existing "standards" regardless  
of whether something else is "better". I don't think anything below  
should place an intolerable burden on anyone.

So, are they OK?

Ben




The coding style should be fairly easy to pick up when looking at the  
source files. But here are some pointers:

Indent with tabs, with 4 character tab stops.

Bracing style:

     if(condition)
     {
     }

Use braces, even if it's a single statement.

Prefer references to pointers.

Function(), if(), switch(), etc... no space before the brackets.

Variable names are prefixed with m (class member), p (pointer), r  
(reference) in that order. Arguments to functions are capitalised  
(ArgumentToFunction, rArgumentToFunction), local variables aren't  
(localVariable). Member variables are caplitalised too, but always  
start with m.

Classes are ClassName (with no prefix), and member functions are  
FunctionName(). Code lives in .cpp and .h files with the same name as  
the class.

Non-member function calls are prefixed with ::, eg ::printf(...).

Exceptions are used. All are autogenerated, and thrown with the  
THROW_EXCEPTION macro. Except for std::bad_alloc, which is thrown  
when memory allocations failed.

Objects are allocated on the stack whereever possible to ease  
exception handling.

No overloading of operators, especially not for i/o. Only exception  
is comparison operators, but even then, only if really justified.  
(Justification: it's not obvious what an operator will do!)

Use the STL wherever useful, but don't use the STL style!

If a function returns a newly allocated object, use an  
std::auto_ptr<> to return it.

Code is split up into logical groups in the lib/* directories,  
although the use of these is minimised.

#include "Box.h" must be the first include in every cpp file. On some  
platforms, failing to do this absolutely first will cause the  
compiled code to crash due to inconsistent options.

There is no global base class.

Serialisation is done using two functions:
         void ReadFromStream(IOStream &rStream, int Timeout);
         void WriteToStream(IOStream &rStream) const;
Serialisable objects are not derived from any particular base class  
as it doesn't seem necessary. Templates can be used if generic code  
is necessary.

All serialised objects use network byte order.