CodeStyleConventions code style conventions

GENERAL ------- Use real tabs that equal 4 spaces. use typically trailing braces everywhere (if, else, functions, structures, typedefs, class definitions, etc .) if (x) {} The else statement starts on the same line as the last closing brace. if (x) {} else {} Pad parenthesized expressions with spaces if (x) {} Instead of if (x) {} And x = (y * 0.5f ); instead of x = (y * 0.5f); Use precis Ion specification for floating point values unless there is an explicit need for a double. float f = 0.5f; Instead of float f = 0.5; And float f = 1.0f; Instead of float f = 1.f; Function names start with an upper case: void Function (void ); in multi-word function names each word starts with an upper case: void ThisFunctionDoesSomething (void); The standard header for functions is:/* ========== ========= FunctionName Description =======================================*/Variable names start with a lower case character. float x; In multi-word variable names the first word starts with a lower case character and each successive word starts with an upper case. float maxDistanceFromPlane; Typedef names use the same naming convention as variables, however they always end with "_ t ". typedef int fileHandle_t; Struct Names use the same naming convention as variables, however they always end with "_ t ". struct renderEntity_t; Enum names use the same naming convention as variables, however they always end with "_ t ". the enum constants use all upper case characters. multiple words are separated with an underscore. enum contact_t {CONTACT_NONE, CONTACT_EDGE, CONTACT_MODELVERTEX, CONTACT_TRMVERTEX}; Names of recursive Functions end with "_ r" void WalkBSP_r (int node); Defined names use all upper case characters. multiple words are separated with an underscore. # define SIDE_FRONT 0 Use 'const' as much as possible. use: const int * p; // pointer to const intint * const p; // const pointer to intconst int * const p; // const pointer to const int Don't use: int const * p; CLASSES ------- The standard header for a cl Ass is: /* ===================================================== ========================================================== = Description = ========================================================== = */Class names start with "id" and each successive word starts with an upper case. class idVec3; Class variables have the same naming convention as variables. class idVec3 {float x; float y; float z;} Class methods have t He same naming convention as functions. class idVec3 {float Length (void) const;} Indent the names of class variables and class methods to make nice columns. the variable type or method return type is in the first column and the variable name or method name is in the second column. class idVec3 {float x; float y; float z; float Length (void) const; const float * ToFloatPtr (void) const;} The * of t He pointer is in the first column because it improves readability when considered part of the type. ording of class variables and methods shoshould be as follows: 1. list of friend classes2. public variables3. public methods4. protected variables5. protected methods6. private variables7. private methods This allows the public interface to be easily found at the beginning of the class. always make CIA Ss methods 'const' when they do not modify any class variables. avoid use of 'const _ cast '. when object is needed to be modified, but only const versions are accessible, create a function that clearly gives an editable version of the object. this keeps the control of the 'const-ness 'in the hands of the object and not the user. return 'const' objects unless the general usage of the object is to cha Nge its state. for example, media objects like idDecls shocould be const to a majority of the code, while idEntity objects tend to have their state modified by a variety of systems, and so are OK to leavenon-const. function overloading shoshould be avoided in most cases. for example, instead of: const idAnim * GetAnim (int index) const; const idAnim * GetAnim (const char * name) const; const idAnim * GetAn Im (float interval) const; Use: const idAnim * GetAnimByIndex (int index) const; const idAnim * GetAnimByName (const char * name) const; const idAnim * GetRandomAnim (float interval) const; Explicitly named functions tend to be less prone to programmer error and inadvertent callto functions due to wrong data types being passed in as arguments. example: Anim = GetAnim (0); This cocould Be meant as a call to get a random animation, but the compiler wowould interpret it as a call to get one by index. overloading functions for the sake of adding 'const' accessible function is allowable: class metadata: public idEntity {idAnimator * GetAnimator (void); const idAnimator * GetAnimator (void) const ;}; in this case, a const version of GetAnimator was provided in order to allow GetAnimator to be called from const functions. since idAnimatedEntity is normally a non-const object, this is allowable. for a media type, which is normally const, operator overloading shoshould be avoided: class idDeclMD5: public idDecl {const idMD5Anim * GetAnim (animHandle_t handle) const; idMD5Anim * GetEditableAnim (animHandle_t handle);}; id Studio Names --------------- id <name> Dlg // dialog c Lassid <name> Ctrl // dialog control classid <name> Frm // frame windowid <name> View // view windowid <name> // any other class file names --------- Each class shold be in a seperate source file unless it makes sense to group several smaller classes. the file name shocould be the same as the name of the class without the "id" prefix. (Upper/lower case is preserved .) class idWinding; files: Winding. cppWindi Ng. h When a class spans using SS multiple files these files have a name that starts with the name of the class without "id", followed by an underscore and a subsection name. class idRenderWorld; files: RenderWorld_load.cppRenderWorld_demo.cppRenderWorld_portals.cpp When a class is a public virtual interface to a subsystem the public interface is implemented in a header file with the name of the clas S without "id ". the definition of the class that implements the subsystem is placed in a header file with the name of the class without "id" and ends with "_ local. h ". the implementation of the subsystem is placed in a cpp file with the name of the class without "id ". class idRenderWorld; RenderWorld. h // public virtual idRenderWorld interfaceRenderWorld_local.h // definition of class idRenderWorld LocalRenderWorld. cpp // implementation of idRenderWorldLocal. Generally, trailing braces (such as if, else, function, struct, definition type, class definition, etc.) are used wherever they are. if (x) the {} else statement starts with the last braces in the same line. if (x) {} else {} is in the braces. if (x) is empty, the expression or variable if (x) is used) {} Instead of if (x) {}, there is x = (y * 0.5f), rather than x = (y * 0.5f). unless there is a definite need for a double-precision value, otherwise, float f = 0.5f, float f = 0.5, float f =, and float f = 1.0f, instead of float f = 1.f; function names start with uppercase: void Function (void); in a multi-word Function name, each word starts with an uppercase statement: void ThisFunctionDoesSomething (void); the standard of comments written at the beginning of each Function is: /* ========================== ===== Function Name Description ===============================*/variable names start with lowercase letters. Float x; the first character of a Multi-character variable name starts with a lowercase character, and each consecutive word starts with an uppercase character. Float maxDistanceFromPlane; the naming rules for defining type names are the same as those for variable names, but the definition type names end with "_ t. Typedef int fileHandle_t; the naming rules of struct names are the same as those of variable names, but struct names end with "_ t. Struct renderEntity_t; the naming rules of enumeration names are the same as those of variable names, but enumeration names end with "_ t. All enumerated constants use uppercase characters. The enumerated variable names of multiple words are separated by underscores. Enum contact_t {CONTACT_NONE, CONTACT_EDGE, CONTACT_MODELVERTEX, CONTACT_TRMVERTEX}; recursive function name ends with "_ r" void WalkBSP_r (int node); macro definition names all use uppercase characters. The macro names of multiple words are separated by underscores. # DefineSIDE_FRONT 0 use const int * p as much as possible; // pointer to const intint * const p; // const pointer to intconst int * const p; // const pointer to const int instead of int const * p; Class ------- the standard for starting each class is: /* ===================================================== ========================================================== = Description ============================================== ========================================================== = */The class name starts with "id, the following words start with an uppercase character. ClassidVec3; the naming rules for class variable names are the same as those for variable names. Class idVec3 {float x; float y; float z;} The naming rules for class methods are the same as those for functions. Class idVec3 {float Length (void) const;} To make a neat column, we indent the variables of class variables and class methods. The return type of the variable type or method is in the first column, and the variable name or method name is in the second column. Class idVec3 {float x; float y; float z; float Length (void) const; constfloat * ToFloatPtr (void) const;} * pointer in the first column, because it is considered part of the type, thus improving readability. The sequence of class variables and methods should be the same as the following: 1. list the Friends Class 2. public variable 3. public Method 4. protection variable 5. protection Method 6. private variable 7. private methods make it easy to find public interfaces at the beginning of the class. When the class method does not modify any class variables, the class method is always defined as 'const' [constant method] to avoid "const_cast ". When the object needs to be modified, but only the constant version can be accessed, create a function, it clearly provides an editable object version. This ensures that the control of 'const-ness 'is in the hands of objects rather than users. Unless the normally used object changes its state, the 'const' object is returned. For example, a media object, such as idDecls, should be a const in most code, while an identity object modifies the status based on various systems and determines non-const. In most cases, function overloading should be avoided. For example, instead of: constidAnim * GetAnim (int index) const; constidAnim * GetAnim (const char * name) const; constidAnim * GetAnim (float randomDiversity) const; instead, use: constidAnim * GetAnimByIndex (int index) const; constidAnim * GetAnimByName (const char * name) const; constidAnim * GetRandomAnim (floatrandomDiversity) const; functions with accurate and clear names are not prone to programmer errors, nor are they prone to inaccurate function calls due to input of wrong data type parameters. For example: Anim = GetAnim (0); this may mean that the call gets a random animation, but the compiler interprets it as calling an index. To add the "constant" access function, the overload function is allowed: class idAnimatedEntity: publicidEntity {idAnimator * GetAnimator (void); const idAnimator * GetAnimator (void) const ;}; in this case, a const GetAnimator version is provided to allow the GetAnimator function to be called by the const function. Because idAnimatedEntity is usually a very large object, this is allowed. For a media type, it is usually a constant, and the operator overload should avoid: class idDeclMD5: public idDecl {const idMD5Anim * GetAnim (animHandle_t handle) const; idMD5Anim * GetEditableAnim (animHandle_t handle );}; id Studio Names --------------- id <name> Dlg // dialog classid <name> Ctrl // dialog control classid <name> Frm // frame windowid <name> View // view windowid <name>> // any other class file name --------- unless it is a meaningful number of smaller classes, otherwise, each class should be in a separate source file. The file name should be the same as the class name without the "id" prefix. (Save in big/lower case .) Class idWinding; files: Winding. cppWinding. h. When a class spans multiple files, these files have a name. The name of the class does not have an "id", followed by an underscore or segment name. Class idRenderWorld; files: RenderWorld_load.cppRenderWorld_demo.cppRenderWorld_portals.cpp When a class is a public virtual interface to a subsystem the public interface is implemented in a header file with the name of the class without "id ". the definition of the class that implements the subsystem is placed in a header file with the name of the class without "id" and ends with "_ local. h ". the implementation of the subsystem is placed in a cpp file with the name of the class without "id ". class idRenderWorld; RenderWorld. h // public virtual idRenderWorld interfaceRenderWorld_local.h // definition of class idRenderWorldLocalRenderWorld. cpp // implementation of idRenderWorldLocal