CnC_Remastered_Collection

Command and Conquer: Red Alert
Log | Files | Refs | README | LICENSE

STYLE.H (4263B)

      1 //
      2 // Copyright 2020 Electronic Arts Inc.
      3 //
      4 // TiberianDawn.DLL and RedAlert.dll and corresponding source code is free 
      5 // software: you can redistribute it and/or modify it under the terms of 
      6 // the GNU General Public License as published by the Free Software Foundation, 
      7 // either version 3 of the License, or (at your option) any later version.
      8 
      9 // TiberianDawn.DLL and RedAlert.dll and corresponding source code is distributed 
     10 // in the hope that it will be useful, but with permitted additional restrictions 
     11 // under Section 7 of the GPL. See the GNU General Public License in LICENSE.TXT 
     12 // distributed with this program. You should have received a copy of the 
     13 // GNU General Public License along with permitted additional restrictions 
     14 // with this program. If not, see https://github.com/electronicarts/CnC_Remastered_Collection
     15 
     16 /*
     17        STYLE GUIDE FOR COMMAND & CONQUER : TIBERIAN SUN
     18 
     19 In addition to the standard Westwood programmer's style guide, the following
     20 guidelines apply.
     21 
     22 > Use every feature the compiler has that will help catch bugs and encourage
     23 solid portable coding practices. i.e., turn on all warnings and treat all warnings
     24 as errors. Use helper programs such as Lint, BoundsChecker, or CodeGuard whenever
     25 possible.
     26 
     27 > Keep related items together. Examples: Declare variables right before they are
     28 used. Keep functions that work on the same subsystem, within the same module.
     29 
     30 > Use consistent commenting and spacing style. Examples: see existing Red Alert
     31 code. Creative freedom does not extend to formatting.
     32 
     33 > Use descriptive variable names. Examples: Use "index" rather than "i". Use
     34 "unit_index" rather than "index".
     35 
     36 > Use a consistent variable and function naming convention. Examples; boolean
     37 variables should begin with "Is" (e.g., "IsActive", "IsFiring"). Functions that
     38 exist solely to return a similar boolean query should begin with "Is_".
     39 
     40 > If you have a variable that only serves a boolean function, then declare it
     41 as "bool" rather than as "int" and assign it "true" or "false" rather than "1"
     42 or "0".
     43 
     44 > Choose function and variable names that are precise, descriptive, and concise (in that
     45 order).
     46 
     47 > Hide data where possible: Examples: If a global is only used in one module, make
     48 it static to that module. If a helper function is only used in one module, make it
     49 static as well. Hide class members in the private section if they aren't needed
     50 public. Most variables aren't needed as public.
     51 
     52 > Keep function bodies short. It is often times, more easy to understand and maintain
     53 if a very long function is broken up into helper functions with descriptive names.
     54 A clue if a function is too long is if you can page down 5 times and still be somewhere
     55 in the middle of the function. If you can page down 10 times and still be in the
     56 function, you've got a serious function size problem.
     57 
     58 > Compare pointers to NULL and integer types to zero (NULL) instead of using the
     59 "if (x)" or "if (!x)" format. This short format should only be used for boolean
     60 values and expressions. It is just as efficient and it makes it more clear to the
     61 reader that the variable is a pointer and not a simple boolean value.
     62 
     63 > Use "const" when declaring any member functions that do not modify data. Corollary --
     64 make sure any function that appears like it will not modify data will, in fact, NOT
     65 modify any data. Example; A function called Is_Able_To_Move() shouldn't modify the
     66 object nor should it actually cause something to start moving! The use of "const" is a
     67 variation on style guide rule #1 (use the compiler to help ensure proper code).
     68 
     69 > Shun using assembly language except in extreme cases. Such would be if a
     70 function can only be performed by using assembly (requires special opcodes), or
     71 if performance would be PROVEABLY dramatically improved. Don't code in assembly for
     72 performance reasons if there isn't benchmarking code in place to analyze the results.
     73 As a corollary, design a better algorithm as the first recourse.
     74 
     75 > Keep class interfaces small and simple.
     76 
     77 > Organize algorithms to use as few special case "if" statements as possible. Data
     78 tables or data files are preferred. This follows the generally good guideline of offloading
     79 as much processing as possible to compile-time rather than run-time.
     80 
     81 */