Code conventions

From Guichan

TODO add a brief description about the code conventions and why they are necessary.

Files

Header files and source files should only contain one class.

Indentation

The indentation level should always be four (4) white spaces. Tabs or not allowed. Brackets should always start at a new line. Brackets should always be used even if they are not necessary. See the if-clause. Below follows examples of indentations.

if (value < 0)
{
    doSomething();
}
else if (value == 0)
{
    doSomethingElse();
}
else
{
    doSomethingCompletelyDifferent();
}

If-clause indentation.

switch (value)
{
    case 0:
        doSomething();
        break;
    case 1:
        doSomethingElse();
        break;
    default:
        doSomethingCompletelyDifferent();
        break;
}

Switch-clause indentation.

while (something)
{
    doSomething();
}

While loop indentation.

do
{

} while (something);

Do-while loop indentation.

int i;
for (i = 0; i < something; i++)
{
    doSomething();
}

For loop indentation. Notice the declaration of the variable i before the for loop. This should be done to make sure Guichan compiles in MSVC6 as MSVC6 has a problem with declared variables inside for loop declarations - they don't lose scope until the end of the body in which the for loop was declared in is reached.

class Something: public SomethingElse
{
public:
    Something();
    ~Something();
protected:
    void someFunction();
};

Class indentation.

enum
{
    SOMETHING = 0,
    SOMETHING_ELSE,
    SOMETHING_COMPLETELY_DIFFERENT
};

Enum indentation.

namespace gcn
{
    class Something
    {
	
    };
}

Namespace indentation.

Naming

Naming follows the Java conventions with a few differences. Member variables should always begin with a small m (indicating that the variable indeed is a member variable) followed by the name beginning with a capital letter.

class Something
{
public:
    Something();
	
protected:
    int mSomething;
    bool mSomething;
    std::vector<long> mLongs;
};

Example of naming member variables. Note that the vector name ends with s to indicate that the member variable mLongs is a collection.

Files should have lower case names and be named after the class the file declares or defines. If a file doesn't include a class it should be given a name that reflects the content of the file in a clear and intuitive way.

Defines along with enum variables should have upper case names. Each word in a define name or enum variable name should be separated with an underscore. Defines should also begin with the Guichan namespace.

#define GCN_WIDGET_HPP

enum Alignment
{
    LEFT,
    CENTER,
    RIGHT
};

Example of naming defines and enum variables.

Documentation

Every Class, enum, function and member variable that is not private should be documented with Doxygen. Doxygen comments should only be placed in header files. Inherited functions should not have doxygen comments, instead it should be clearly stated from which class the inherited methods comes from, it's best done by placing a small comment above inherited functions.

Inherited functions should be put last in the class header file. Inherited functions should also be separated from the other functions of the class by placing an extra empty line above the inherited functions.

Documentation in the form of comments should always be placed above the line of code the comment concerns. Only //-comments should be used. Below follows examples of documentation.

namespace gcn
{
    /**
     * Demonstrates the usage of Doxygen.
     */
    class Something : public Interface
    {
    public:
        /**
         * Constructor.
         */
        Something();
		
        /**
         * Destructor.
         */
        ~Something();	
	
        /**
         * Gets something.
         *
         * @return Something.
         */
        int getSomething();
		
        /**
         * Sets something.
         *
         * @param something The something to set.
         * @throws Exception when something equals zero.
         */
        void setSomething(int something);
		
		
        // Inherited from Interface
		
        void interfaceFunction();
		
    protected:
        int mSomething;
    };
}

An example of a doxygen commented class which inherits from an interface.

// If the value equals zero then we know we are done
// and calls exit.
if (value == 0)
{
    exit();
}

Example of documentation in form of a comment.