AppleWin/docs/CodingConventions.txt

Coding Conventions for AppleWin
===============================

History:
v2 - 16-Feb-2006 (TC)
. Updated after discussion with M.Pohoreski
v1 - 04-Feb-2006 (TC)
. First draft

-------------------------------------------------------------------------------

Introduction:
-------------

This doc defines a very simple set of coding guidelines to be used for AppleWin.
This ensures consistency & readability throughout the project, when worked on
by multiple developers.

-------------------------------------------------------------------------------

1) Project files:

1.1: Each module to have corresponding header
EG. Debug.cpp has a corresponding Debug.h
This is for shared vars, enums, structs, classes, etc.

1.2: AppleWin.h to only be used as per 1.1

1.3: Common.h to be used for any common definitions
EG. const/enum/struct
Obviously not for global funcs or vars.

1.4: At the start of each header file it must contain: #pragma once

1.5: Each module (.cpp) to include stdafx.h, and then immediately after include
the header file for that module.
EG. For Debug.cpp:
#include "stdafx.h"
#include "Debug."

This ensures that this header file can be included in any order in another module,
and therefore by extension all header files can be included in any order.

-------------------------------------------------------------------------------

2) Coding Style:

2.1: Naming
The following simplied Hungarian style must be used:

Prefixes:
a	: array
b	: bool
e	: enum variable
g_	: global
h	: handle
i	: iterator (eg. UINT, STL-iterator)
m	: STL map
m_	: member
n	: int
p	: pointer
r	: reference
s	: string
sg_p	: singleton (could also use 'sgp' - to be reviewed)
u	: unsigned int
v	: STL vector

Tags:
_e	: named enum definitions
_t	: struct/typedef

Legacy:
dw	: DWORD [legacy: existing 'dw' to be replaced with 'u' prefix]
sz	: string (null-terminated) [legacy: 

EG:
	enum MODE_e {MODE1, MODE2, MODE2};
	MODE_e eMode;
	
	struct PAIR_t
	{
		UINT uA;
		UINT uB;
	};

Simple loop counters (i,j,k) don't need to adhere to this style.

Don't go Hungarian-mad (you might argue that we already have :)
. an array of any type can just be prefixed with 'a'. Eg. Array of bools:
	bool aFlags[NUM_FLAGS];
. a pointer to any type can just be prefixed with 'p'. Eg. Pointer to array of bools:
	bool* pFlags;

Naming for parameters that are being modified (eg. OUT):
It is recommended (but not mandatory) to use a suffix of OUT or '_', eg:
	bool Find(int* pFoundOUT);
	bool Find(int* pFound_);


2.2: Matching braces
These should be have same indentation, unless the braces fit neatly on one line.
EG:
	for (int i=0; i<10; i++)
	{
		// Some code
	}

2.3: Scope of module vars/funcs
If module vars/funcs aren't wrapped in a class, then declare as static if not global.

2.4: const/enum favoured over #define
Try to use const/enum instead of #define

2.4: Use of bool over BOOL
Always use bool instead of BOOL

2.5: File header
GPL header, followed by description of module & author.

2.6: Indentation
Tabs favoured over spaces.

2.7: Expression to be well spaced and parenthesised
It is recommended (but not mandatory):
. to have/use explicit parenthesis
. to have spaces between operators

Eg:
. Prefer: z = ((a + b) + 1) instead of: z=((a+b)+1)