Coding Standards

(This page is currently a work in progress)

D

Spacing

Spaces

Use 4 spaces for indentation. Do not use hardware tabs.

Braces

Put braces on the next line, everywhere (if, else, functions, structures, class definitions, etc.)

if( x )
{
    // Code
}

The else statement starts on the next line after the last closing brace.

if( x )
{
    // Code
}
else
{
    // More code
}

Array initialization

Arrays should be inititialized using prefix notation. Meaning use this:

int[] foo;

and not:

int bar[];

Parenthesized expressions

Pad parenthesized expressions with spaces

if( x )
{
    // Code
}

Instead of

if(x)
{
    // Code
}

And

x = ( y * 0.5f );

Instead of

x = (y * 0.5f);

Floating Point Precision

Use precision specification for floating point values unless there is an explicit need for a double.

float f = 0.5f;

Instead of

float f = 0.5;

And

float f = 1.0f;

Instead of

float f = 1.f;

Naming Conventions

Functions

Function names start with a lower case.

void func( void );

In multi-word function names each word starts with an upper case, except for the first one.

void thisFunctionDoesSomething( void );

Variables

Variable names start with a lower case character.

float x;

In multi-word variable names the first word starts with a lower case character and each successive word starts with an upper case.

float maxDistanceFromPlane;

Structs and Classes

Struct and class names should be pascal cased.

struct RenderEntity;

Aliased types use the same naming convention.

alias FileHandle = int;

Enums

Enum names use the same naming convention as Classes. The enum constants should be pascal cased.

enum Contact
{
	None,
	Edge,
	ModelVertex,
	TRMVertex
};

Const and Immutable

Use const and immutable as much as possible.

Use:

const int* p;			// pointer to const int
immutable int i;                // Immutable, global int

Assert and Exceptions

Exceptions should be used when the error results in the application closing, but allows for a message to the user that something is broken. An example of when we would use this would be if the version of OpenGL we are using is not supported on a user's machine, an exception would be thrown, an error message shown, and the application closing. Exceptions should not be used when the error is recoverable.

static assert() may be used when the issue is template-based and can be caught at compile time.

Documentation

Document all methods using DLang documentation comments.

Classes

Class names start with an upper case and each successive word starts with an upper case.

class Vector3;

Class variables have the same naming convention as variables.

class Vector3
{
	float		x;
	float		y;
	float		z;
}

Class methods have the same naming convention as functions.

class Vector3
{
	float		length( void ) const;
}

Indent the names of class variables and class methods to make nice columns. The variable type or method return type is in the first column and the variable name or method name is in the second column.

class Vector3
{
	float		x;
	float		y;
	float		z;
	float		length( void ) const;
	const float*	toFloatPtr( void ) const;
}

Ordering of class variables and methods should be as follows:

1. static members
2. public variables
3. public methods
4. protected variables
5. protected methods
6. private variables
7. private methods

This allows the public interface to be easily found at the beginning of the class.

Always make class methods ‘const’ when they do not modify any class variables.

Return ‘const’ objects unless the general usage of the object is to change its state. For example, media objects like Decls should be const to a majority of the code, while Entity objects tend to have their state modified by a variety of systems, and so are ok to leave non-const.

Function overloading should be avoided in most cases. For example, instead of:

	const Anim*	getAnim( int index ) const;
	const Anim*	getAnim( const char *name ) const;
	const Anim*	getAnim( float randomDiversity ) const;

Use:

	const Anim*	getAnimByIndex( int index ) const;
	const Anim*	getAnimByName( const char *name ) const;
	const Anim*	getRandomAnim( float randomDiversity ) const;

Explicitly named functions tend to be less prone to programmer error and inadvertent calls to functions due to wrong data types being passed in as arguments. Example:

Anim a = getAnim( 0 );

This could be meant as a call to get a random animation, but the compiler would interpret it as a call to get one by index.

Array Declarations

Note that although all of these are the same:

// array of 3 arrays of 4 ints each
int[4][3] b;
int[4] b[3];
int b[3][4];

Please only use this style:

int[4][3] b;

File Names

Each class should be in a seperate source file unless it makes sense to group several smaller classes. The file name should be the same as the name of the class, but in lower case.

class Winding;

files:

winding.d

GLSL

Where this and the D standards conflict, choose these when writing GLSL. Otherwise, maintain the same standards as in the D standards

Naming Conventions

Variables

Input & Output Variables

Any variables which are passed into a shader, or between shaders, should specify the shader stage where the variables come in by the first letter of the shader stage. Example:

//vertex shader
in vec3 vPosition_m;
out vec3 fPosition_w; //f, because this will be an input for the fragment shader

Variables should also contain a suffix to represent the coordinate space of the variable, such as world space, view space, or screen space, with the following suffixes:

• Model space: _m
• Tangent space: _t
• World space: _w
• View space: _v
• Screen space: _s