AppleWin/docs/CodingConventions.txt

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

History:
v3 - 14-Nov-2020 (TC)
. #868: Reduced Hungarian notation
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
For functions use upper camel case.

For variables use lower camel case.
And if applicable, the following simplied prefix (Hungarian) style must be used:

Prefixes:
g_	: global
m_	: member
p	: pointer

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

Legacy:
dw	: DWORD
sz	: string (null-terminated)
a	: array
b	: bool
e	: enum variable
h	: handle
i	: iterator (eg. UINT, STL-iterator)
m	: STL map
n	: int
r	: reference
s	: string
sg_p	: singleton
u	: unsigned int
v	: STL vector

EG:
	enum MODE_e {MODE1, MODE2, MODE2};
	MODE_e mode;
	
	struct PAIR_t
	{
		UINT a;
		UINT b;
	};

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

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)

2.8: For consistency, adopt the coding convention of any module (or function) you are modifying.