mirror of
https://github.com/AppleWin/AppleWin.git
synced 2024-12-22 09:30:15 +00:00
231 lines
6.2 KiB
Plaintext
231 lines
6.2 KiB
Plaintext
Coding Conventions for AppleWin
|
|
===============================
|
|
|
|
History:
|
|
v7 - 23-Mar-2023 (MP)
|
|
. Clarify 2.1 Naming
|
|
. Split into sub-section 2.1.1: Simplified prefix names
|
|
. Split into sub-section 2.1.2: Loop conters
|
|
. Split into sub-section 2.1.3: Out parameters
|
|
. Clarify 2.6 Indentation
|
|
. Add 2.6.1: Brace placement
|
|
. Add 2.6.1.1: Debugger function style
|
|
. Clarify b, and n prefix
|
|
v6 - 12-Jan-2023 (TC)
|
|
. Avoid global vars & provide getter/setter accessor functions.
|
|
. Avoid C++11 empty initializer lists. (PR#634)
|
|
v5 - 03-Apr-2022 (TC)
|
|
. #1072: Add a space after keywords.
|
|
v4 - 05-Mar-2022 (TC)
|
|
. #1050: Added info about Platform Toolset v141_xp
|
|
. Use of C++11/14/17
|
|
. Use StrFormat() instead of sprintf() etc.
|
|
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.h"
|
|
|
|
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:
|
|
|
|
As a general rule and for consistency, adopt the coding convention/style of any module (or function) you are modifying.
|
|
|
|
2.1: Naming
|
|
For functions use upper camel case (PascalCase).
|
|
|
|
For variables use lower camel case (camelCase).
|
|
|
|
2.1.1: Simplified prefix names
|
|
And only if applicable, the following simplified prefix (Hungarian) style can be used:
|
|
|
|
Prefixes:
|
|
g_ : global
|
|
m_ : member
|
|
p : pointer
|
|
|
|
Tags:
|
|
_e : named enum definitions
|
|
_t : struct/typedef
|
|
|
|
Also see: "Appendix: Legacy Hungarian notation"
|
|
|
|
EG:
|
|
enum MODE_e {MODE1, MODE2, MODE2};
|
|
MODE_e mode;
|
|
|
|
struct PAIR_t
|
|
{
|
|
UINT a;
|
|
UINT b;
|
|
};
|
|
|
|
2.1.2: Loop conters
|
|
Simple loop counters (i,j,k) don't need to adhere to this style.
|
|
NOTE: It would be better to use a better descriptive loop name then a non-descript single character variable name.
|
|
|
|
2.1.3: Out parameters
|
|
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. (Tabs for indent, spaces for alignment.)
|
|
|
|
2.6.1: Brace placement
|
|
Braces should be formated with Allman Style (opening brace on separate line) and NOT K&R style (opening brace on same indentation level as its header).
|
|
EG:
|
|
void FindFoo() // GOOD
|
|
{
|
|
}
|
|
|
|
void FindFoo() { // BAD
|
|
}
|
|
|
|
See: https://en.wikipedia.org/wiki/Indentation_style
|
|
|
|
2.6.1.1: Debugger function style
|
|
For functions in the debugger, both the
|
|
|
|
* function declaration,and
|
|
* function definition
|
|
|
|
MUST have a space between the end of the function name and the opening parenthesis.
|
|
This makes it trivial to search and jump to the function implementation since every function call _won't_ have that extra space.
|
|
EG:
|
|
void FindFoo (); // .h
|
|
|
|
void FindFoo () // .cpp
|
|
{
|
|
}
|
|
|
|
void Bar()
|
|
{
|
|
if (FindFoo() // usage
|
|
}
|
|
|
|
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: Add a space after keywords (if, for, switch, while, etc).
|
|
|
|
EG:
|
|
for (int i=0; i<10; i++)
|
|
|
|
Not:
|
|
for(int i=0; i<10; i++)
|
|
|
|
2.9: Avoid global variables.
|
|
|
|
If a free variable exists within a C++ file, then declare it static and provide getter & setter accessor functions.
|
|
|
|
-------------------------------------------------------------------------------
|
|
|
|
3) Use of sprintf() etc.
|
|
|
|
Do not use sprintf(), StringCbPrintf(), wsprintf(), etc. - instead use StrFormat().
|
|
|
|
-------------------------------------------------------------------------------
|
|
|
|
4) Use of C++
|
|
|
|
VS2019's Platform Toolset "Visual Studio 2017 - Windows XP(v141_xp)" is used for building releases.
|
|
This is VS2017 v15.0, which includes support for C++11, C++14 and some C++17 core language support[1].
|
|
|
|
[1] https://docs.microsoft.com/en-us/cpp/overview/visual-cpp-language-conformance?view=msvc-170
|
|
|
|
4.1: Type deduction (including auto)
|
|
|
|
Use type deduction only if it makes the code clearer to readers who aren't familiar with the project,
|
|
or if it makes the code safer. Do not use it merely to avoid the inconvenience of writing an explicit type.
|
|
(Ref: https://google.github.io/styleguide/cppguide.html#Type_deduction)
|
|
|
|
4.2: Avoid C++11 empty initializer lists
|
|
|
|
This notation can be too obscure, compared to using regular initialization (for POD) or ctors (for classes).
|
|
EG, avoid this:
|
|
int var {};
|
|
struct s {};
|
|
|
|
-------------------------------------------------------------------------------
|
|
|
|
Appendix: Legacy Hungarian notation
|
|
|
|
dw : DWORD
|
|
sz : string (null-terminated)
|
|
a : array
|
|
b : bool or bitmask
|
|
e : enum variable
|
|
h : handle
|
|
i : iterator (eg. UINT, STL-iterator)
|
|
m : STL map
|
|
n : int, total, or length
|
|
r : reference
|
|
s : string
|
|
sg_p : singleton
|
|
u : unsigned int
|
|
v : STL vector
|