/* ================================ 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 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); }