|
| 1 | +--- |
| 2 | +layout: default |
| 3 | +title: Style Guide |
| 4 | +nav_order: 2 |
| 5 | +--- |
| 6 | + |
| 7 | +# Code Style Guide. |
| 8 | +{: .fs-9 } |
| 9 | + |
| 10 | +--- |
| 11 | + |
| 12 | +Naming Conventions: |
| 13 | +{: .fs-6 } |
| 14 | + |
| 15 | +--- |
| 16 | + |
| 17 | +- Variables: Use camelCase for local variables. Prefix global variables with `g_` and static class variables with `s_`, followed by camelCase: |
| 18 | + |
| 19 | + ```cpp |
| 20 | + int countEnts; |
| 21 | + int g_globalData; |
| 22 | + bool s_mapParse; |
| 23 | + ``` |
| 24 | + |
| 25 | +- Functions and Methods: Use camelCase, starting with a verb that describes the function's action: |
| 26 | +
|
| 27 | + ```cpp |
| 28 | + void IdActor::myAwesomeFunction() { |
| 29 | + /* Some code goes here */ |
| 30 | + } |
| 31 | + ``` |
| 32 | +
|
| 33 | +- Classes and Structs: Use PascalCase. Prefix interfaces with I and abstract classes with Abstract: |
| 34 | +
|
| 35 | + ```cpp |
| 36 | + struct idStructExample { |
| 37 | + int structVariable; |
| 38 | + }; |
| 39 | + ``` |
| 40 | +
|
| 41 | + {: .note } |
| 42 | + > Official release idtech4 codebases names their interfaces/Classes with different names `hh` for HumanHead (Prey 2006) and `rv` for RavenSoftware (Quake 4). |
| 43 | +
|
| 44 | +- Constants and Enums: Use `UPPER_CASE` with underscores between words: |
| 45 | +
|
| 46 | + ```cpp |
| 47 | + typedef enum { |
| 48 | + ENUM_ONE, |
| 49 | + ENUM_TWO, |
| 50 | + ENUM_THREE |
| 51 | + } enumListType_t; |
| 52 | + ``` |
| 53 | +
|
| 54 | +
|
| 55 | +- Files: Source files (.cpp) and header files (.h) should match the class name they define. Use lower_case with underscores for non-class-specific files: |
| 56 | +
|
| 57 | + ``` |
| 58 | + +-- .. |
| 59 | + |-- (Doom 3 GPL Release) |
| 60 | + | |
| 61 | + |-- game |
| 62 | + | |-- Entity.cpp |
| 63 | + | |-- Entity.h |
| 64 | + | |-- Game_Local.h |
| 65 | + | |-- Game_Something.h |
| 66 | + | |
| 67 | + +-- .. |
| 68 | + ``` |
| 69 | +
|
| 70 | +Formatting and Style: |
| 71 | +{: .fs-6 } |
| 72 | +
|
| 73 | +--- |
| 74 | +
|
| 75 | +- Brace Style: Use the [K&R BSD KNF style](https://en.wikipedia.org/wiki/Indentation_style#K&R_style), with open brace on the same line: |
| 76 | +
|
| 77 | + ```cpp |
| 78 | + void IdActor::SetFOV( float fov ) { |
| 79 | + } |
| 80 | + ``` |
| 81 | +
|
| 82 | +- Pointer and Reference Symbols: Attach to the type, not the variable name. |
| 83 | +- One Statement Per Line: Avoid multiple statements on the same line to enhance readability. |
| 84 | +- Indentation: Use tabs, not space, with a size of 2 tabs per indentation level. |
| 85 | +- Spaces: Use spaces around operators and after commas to improve readability. |
| 86 | +- Line Length: Try to keep lines under 80 characters when possible, breaking longer lines logically. |
| 87 | +
|
| 88 | +Comments and Documentation: |
| 89 | +{: .fs-6 } |
| 90 | +
|
| 91 | +--- |
| 92 | +
|
| 93 | +- Use doxygen-style comments for documenting classes, methods, and functions: |
| 94 | +
|
| 95 | + ```cpp |
| 96 | + /* |
| 97 | + ===================== |
| 98 | + idCameraView::Stop |
| 99 | + ===================== |
| 100 | + */ |
| 101 | + ``` |
| 102 | +
|
| 103 | +- Place brief descriptions on the same line as the comment start, and detailed descriptions on subsequent lines: |
| 104 | +
|
| 105 | + ```cpp |
| 106 | + /* |
| 107 | + ================ |
| 108 | + idGameEdit::ParseSpawnArgsToRenderEntity |
| 109 | +
|
| 110 | + parse the static model parameters |
| 111 | + this is the canonical renderEntity parm parsing, |
| 112 | + which should be used by dmap and the editor |
| 113 | + ================ |
| 114 | + */ |
| 115 | + ``` |
| 116 | +
|
| 117 | +- Comment every class, public method, and complex block of code to explain intent, not how the code works. |
| 118 | +
|
| 119 | +Best Practices: |
| 120 | +{: .fs-6 } |
| 121 | +
|
| 122 | +--- |
| 123 | +
|
| 124 | +- Initialize all variables upon declaration: |
| 125 | +
|
| 126 | + ```cpp |
| 127 | + class idActor : public idAFEntity_Gibbable { |
| 128 | + /* IdActor code goes here... */ |
| 129 | +
|
| 130 | + bool dontBleed; |
| 131 | +
|
| 132 | + /* IdActor code goes here... */ |
| 133 | + } |
| 134 | +
|
| 135 | + class idActor::IdActor() { |
| 136 | + dontBleed = false; |
| 137 | + } |
| 138 | + ``` |
| 139 | +
|
| 140 | +- Prefer const correctness. Use const wherever possible. |
| 141 | +- Explicitly define copy constructors and assignment operators for classes managing resources. |
| 142 | +- Prefer C++ casts over C-style casts. |
| 143 | +- Use nullptr instead of NULL or 0 for pointer initialization and comparison. |
| 144 | +- Adhere to the Rule of Three/Five, providing custom copy constructor, copy assignment operator, and destructor when you manually manage resource allocation. |
| 145 | +- Organize class definitions with public members first, followed by protected, then private. |
| 146 | +- Prefer prefix over postfix increment/decrement operators for non-primitive types. |
| 147 | +
|
| 148 | +File Organization: |
| 149 | +{: .fs-6 } |
| 150 | +
|
| 151 | +--- |
| 152 | +
|
| 153 | +- Header files should start with a guard to prevent multiple inclusions and include only necessary headers to minimize dependencies. |
| 154 | +- Group include directives logically, starting with standard library headers, followed by third-party libraries, and then project-specific headers. |
0 commit comments