mirror of https://github.com/n64decomp/007.git
268 lines
9.9 KiB
Plaintext
268 lines
9.9 KiB
Plaintext
/*
|
|
================================ Style Guide ==================================
|
|
|
|
GE/PD mostly uses namespaceFunctionName()
|
|
joyTickRetrace();
|
|
aiIfOpportunityFireJumpF();
|
|
with occasional Pascal_Snake_Case
|
|
Snd_Play_Universal()
|
|
and snake_case
|
|
font_makegt
|
|
however sometimes its Snake_PrefixPascalCase
|
|
Pak_AddOneCameraFile
|
|
|
|
GE Constant example
|
|
MAX_FUDGE_DATA_SIZE
|
|
|
|
SDK also mostly uses namespaceFunctionName() in camelCase
|
|
alSndpPlay()
|
|
|
|
Basically, Rare had no style guide!
|
|
|
|
|
|
|
|
If an original name is known - Use it!
|
|
|
|
In all other cases follow this guide.
|
|
|
|
|
|
|
|
_______________________________________________________________________________
|
|
Prefix Table
|
|
_______________________________________________________________________________
|
|
Prefix Meaning Example Notes
|
|
-------|---------------|-------------------|-----------------------------------
|
|
g global gPrefService Not needed if already prefixed
|
|
"Global"
|
|
-------|---------------|-------------------|-----------------------------------
|
|
a argument aCount;
|
|
func(aCount);
|
|
-------|---------------|-------------------|-----------------------------------
|
|
s static member sPrefChecked Static Local retains value over App
|
|
life, but remains local
|
|
-------|---------------|-------------------|-----------------------------------
|
|
m private member -------file1------- a C file (Not H)
|
|
|
|
static mLength; mLength is only accessable to file1
|
|
|
|
GetLength() because mLength was declared
|
|
{ Static.
|
|
return mLength;
|
|
}
|
|
|
|
-------Header------ Header included anywhere
|
|
|
|
extern GetLength(); GetLegnth() is global because it
|
|
was declared extern.
|
|
-------|---------------|-------------------|-----------------------------------
|
|
E_ enum constants enum E_FOO
|
|
{
|
|
E_FOO_BAR, Also prefix with Enum Name.
|
|
E_FOO_BAZ
|
|
}
|
|
-------|---------------|-------------------|-----------------------------------
|
|
_ Implementation __osThingy Underscore prefix should NOT be
|
|
__ (Reserved) used in game code.
|
|
However, expect to find them in OS
|
|
as Internal Identifiers but no
|
|
Accessable Identifier will start
|
|
with _ or __.
|
|
-------|---------------|-------------------|-----------------------------------
|
|
|
|
|
|
Sufix Meaning Example Notes
|
|
-------|---------------|-------------------|-----------------------------------
|
|
p Pointer glistp Pointer to glist
|
|
_______________________________________________________________________________
|
|
|
|
|
|
TYPES
|
|
Use SDK types (u8, s32 etc) rather than C Types (unsigned char, int etc)
|
|
Remember to include <ultra64.h>
|
|
|
|
CONSTANTS
|
|
ALL_CAPS for constants eg. #define NULL 0
|
|
|
|
INCLUDE UNITS IN NAMES
|
|
If a variable represents time, weight, or some other unit then include the unit
|
|
in the name so developers can more easily spot problems.
|
|
For example:
|
|
int timeout_msecs;
|
|
int my_weight_lbs;
|
|
|
|
VARIABLE NAMES
|
|
Should be nouns (as they represent state). The name should be camelCase
|
|
(e.g. index, currentEnvironment or bond).
|
|
|
|
Prefixes are sometimes usefull, please refer to prefix table above
|
|
|
|
Suffixes are sometimes useful eg:
|
|
max - to mean the maximum value something can have.
|
|
cnt - the current count of a running count variable.
|
|
key - key value.
|
|
For example: retry_max to mean the maximum number of retries, retry_cnt to mean
|
|
the current retry count.
|
|
|
|
|
|
FUNCTION NAMES
|
|
Should be verb phrases (as they represent actions), and command-like function
|
|
should be imperative.
|
|
The name should make clear what it does:
|
|
check_for_errors() instead of error_check(),
|
|
dump_data_to_file() instead of data_file().
|
|
This will also make functions and data objects more distinguishable.
|
|
|
|
Prefixes are sometimes useful:
|
|
is - to ask a question about something. Whenever someone sees Is they will
|
|
know it's a question.
|
|
get - get a value. set - set a value.
|
|
|
|
For example: isAlive
|
|
|
|
STRUCT NAMES
|
|
Structs are often nouns and should be PascalCase
|
|
|
|
|
|
COMMENTS
|
|
Comments should be C style / * * / for block comments and header documentation
|
|
C++ style / / for inline comments documenting single items
|
|
XML Documentation for Intelisense / / / should precede functions directly
|
|
without extra line breaks
|
|
|
|
|
|
SCOPE
|
|
Variables inside braces have "Block" scope and end when the block ends (unless
|
|
declared static where they retain their value till program ends). if(1)
|
|
{
|
|
int a = 1;
|
|
}
|
|
else
|
|
{
|
|
int a = 0;
|
|
}
|
|
|
|
Variables Outside functions, usually at top of file (or in header) have by
|
|
default Global Scope (extern aka Public).
|
|
If declaired as static they are demoted to "Translation Unit" Scope,
|
|
(the file including any included files) and cannot be addressed by other
|
|
files (aka Private).
|
|
Both extern and static have Static Duration - they end when the program ends.
|
|
|
|
//Initial Declaration
|
|
int gi1 = 1; // defnition, external linkage (Public)
|
|
static int ii2 = 2; // defnition, internal linkage (Private)
|
|
extern int gi3 = 3; // defnition, external linkage (Public)
|
|
int gi4; // tentative defnition, external linkage (Public)
|
|
static int ii5; // tentative defnition, internal linkage (Private)
|
|
|
|
//Attempted Referencing
|
|
int gi1; // valid tentative defnition, refers to previous
|
|
int ii2; // 6.2.2 renders undefned, linkage disagreement
|
|
int gi3; // valid tentative defnition, refers to previous
|
|
int gi4; // valid tentative defnition, refers to previous
|
|
int ii5; // 6.2.2 renders undefned, linkage disagreement
|
|
|
|
//Reference (Brings into Scope)
|
|
extern int gi1; // refers to previous, whose linkage is external
|
|
extern int ii2; // refers to previous, whose linkage is internal
|
|
extern int gi3; // refers to previous, whose linkage is external
|
|
extern int gi4; // refers to previous, whose linkage is external
|
|
extern int ii5; // refers to previous, whose linkage is internal
|
|
|
|
|
|
|
|
=================== EXAMPLE C ======================
|
|
*/
|
|
|
|
|
|
/* -- FILE 1 -- */
|
|
|
|
static f32 mAiTime; // Static, holds value for duration of program, scoped to file 1
|
|
// There should be good reason to keep a limited scope.
|
|
|
|
/// Returns the time
|
|
extern f32 ai_get_Time() //Explicit extern for clarity (not required)
|
|
{
|
|
return mAiTime; // Gets time from private mTime
|
|
}
|
|
|
|
/// sets the time from an integer
|
|
void ai_set_Time(u32 time) // though not explicit, this is still extern
|
|
{
|
|
mAiTime = time / 60; // Sets time to mTime format
|
|
}
|
|
/*----------------------------------*/
|
|
|
|
|
|
|
|
|
|
|
|
/* -- Global Header (Perhaps included with ultra64.h) -- */
|
|
|
|
extern int ai_get_Time(); // Gets time from private mTime
|
|
|
|
/*----------------------------------*/
|
|
|
|
|
|
|
|
|
|
|
|
|
|
/* -- FILE 2 -- */
|
|
|
|
s32 D_80000000; // Unknown label data (extern by default)
|
|
u32 gGlobalData = 0; // camelCasedNaming and defined as early as possible
|
|
|
|
typedef enum E_ID // prefix with E_
|
|
{
|
|
E_ID_AGENT, // prefix with enum name
|
|
E_ID_SECRETAGENT,
|
|
E_ID_00AGENT
|
|
};
|
|
|
|
typedef struct Person // structs themselves should use PascalCase and be Nouns
|
|
{
|
|
E_ID ID; // struct member Noun and PascalCase
|
|
char *Name;
|
|
int Age;
|
|
} Person;
|
|
|
|
Person gTrevor = {E_ID_00AGENT, "Trevor", 30}; // Global Person defined early
|
|
|
|
// This can be done, but its pointless since gGlobalData has global scope and nothing special is being done
|
|
int get_GlobalData()
|
|
{
|
|
return gGlobalData;
|
|
}
|
|
|
|
|
|
/// functions should be snake_cased
|
|
/// further xml documentation
|
|
/// parameter1 is a s32 and defines the number of xxx
|
|
void function_name_sample(int Parameter1)
|
|
{ // newline for opening braces (ALLMAN)
|
|
u32 tempvar; // Use SDK Types
|
|
|
|
if (gGlobalData == 1)
|
|
{
|
|
gGlobalData = 2;
|
|
D_80000000 = 10;
|
|
}
|
|
else
|
|
{
|
|
tempVar = get_GlobalData(); // wastes cpu instructions
|
|
tempVar = gGlobalData(); // This works equally as well
|
|
}
|
|
|
|
if (gGlobalData == 4)
|
|
gGlobalData = 2; // this syntex may be used
|
|
}
|
|
|
|
void main()
|
|
{
|
|
int aSomeArg = ai_get_Time(); // Access Global Getter
|
|
//aSomeArg = mAiTime; // This fails as mAiTime is not visible in this file (Scope limited to file1)
|
|
function_name_sample(aSomeArg);
|
|
}
|
|
|