UNFINISHED. NOT FOR ANY CONSIDERATION AT THIS TIME

UNFINISHED. NOT FOR ANY CONSIDERATION AT THIS TIME

UNFINISHED. NOT FOR ANY CONSIDERATION AT THIS TIME

Coding Conventions

This document describes the source code grammar conventions that must be followed in Epiar to ensure consistency and sanity. It is done by example, with justification where necessary.

Source Header

/*
 * Filename      : ui.cpp
 * Author(s)     : Chris Thielen (chris@luethy.net)
 * Date Created  : Unknown (2006?)
 * Last Modified : Saturday, January 5, 2008
 * Purpose       :
 * Notes         :
 */

Alphabetical Include Order, Segmented by Facility

#include "Graphics/video.h"
#include "includes.h"
#include "common.h"
#include "Utilities/log.h"
#include "UI/ui.h"

// for ui_demo()
#include "Input/input.h"
#include "Utilities/timer.h"

Macros First, then Functions, then Variables

list<Widget *> UI::children;
Widget *UI::mouseFocus, *UI::keyboardFocus; // remembers which widgets last had these focuses

Tab-Indent Only

Use real tab characters (\t). You can always set the tab width in your editor to your preference.

UI::UI() {
	mouseFocus = NULL;
	keyboardFocus = NULL;
}

UI::~UI() {
	list<Widget *>::iterator i;

	for( i = children.begin(); i != children.end(); ++i ) {
		delete (*i);
	}

	children.clear();
}

No 'f' on floats with decimals

It is both redundant and unnecessary to specify the 'f' on values which already contain decimals.

Here is an example of what not to do:

float d = 0.15f;
float e = 15.0f

Here is what you do:

float d = 0.15;
float e = 3.;

Be sure to simply use an extra '.' (dot) for floating points that are also whole numbers. Though is may not be as readable at 4:00am as "3f", your compiler will catch it and using only the dot notation keeps the code consistent and clean.

Use Spacing Like Deodorant

A proper use of whitespace makes code readable and feel clean. Be sure to use it correctly.

Here is what not to do:

//a comment

some_function(x,y);

Instead, do this:

// a comment

some_function( x, y ); // let the braces breathe

More don'ts:

(radarSize>=1) ?radarSize: 1

Corrected here:

(radarSize >= 1) ? radarSize : 1

Comments

Comments are important. Do not state the obvious, but make sure somebody who didn't write the code can follow the narrative. Write a little extra when it's a more complicated or unorthodox section.

Do not make comments like this:

/**\class Input
 * \brief Input handling. i am full of extra slashes, so bad */

// wow
// this is bad!

int a = 5; /* what a hard thing to type */

Do make comments like this:

/* class Input
 * brief Input handling. and clean comments!
 */

// wow this is good because it's a single line

int a = 5; // what a quick comment

We do it this way because C-style comments like // make sense for multi-line comments and are good for one line comments or end of line, post-code comments (C++ style comments).