HACKING

   1
   2 Coding style guidelines
   3 =======================
   4
   5 The coding style guidelines for Chocolate Doom are designed to keep the
   6 style of the original source code.  This maintains consistency throughout
   7 the program, and does not require the original code to be changed. Some
   8 of these guidelines are stricter than what was done in the original
   9 source; follow these when writing new code only: there is no need to
  10 change existing code to fit them.
  11
  12 You should set tabs to _display_ as eight spaces, not four.  However,
  13 _indentation_ should be four spaces.  If possible, do not use tab
  14 characters at all.  There is a utility called "expand" which will remove
  15 tab characters.  For the reasoning behind this, see:
  16 http://www.jwz.org/doc/tabs-vs-spaces.html
  17
  18 Please write code to an 80 column limit so that it fits within a standard
  19 80 column terminal.
  20
  21 Functions should be named like this: 'AB_FunctionName'.  The 'AB' prefix
  22 denotes the subsystem (AM_ for automap, G_ for game, etc).  If a
  23 function is static, you can omit the prefix and just name it like
  24 'FunctionName'.  Functions and global variables should always be made
  25 static if possible.
  26
  27 Put '_t' on the end of types created with typedef.  Type names like this
  28 should be all lowercase and have the subsystem name at the start. An
  29 example of this is 'txt_window_t'.  When creating structures, always
  30 typedef them.
  31
  32 Do not use Hungarian notation.
  33
  34 Do not use the goto statement.
  35
  36 Use C++-style comments, ie. '//' comments, not '/* ... */' comments.
  37 I don't care that this isn't standard ANSI C.
  38
  39 Variables should be named like this: 'my_variable_name', not like this:
  40 'MyVariableName'.  In pointer variable declarations, place the '*' next
  41 to the variable name, not the type.
  42
  43 When using an if, do, while, or for statement, always use the { } braces
  44 even when they are not necessary.  For example, do this:
  45
  46     if (condition)
  47     {
  48         body;
  49     }
  50
  51 Not this:
  52
  53     if (condition)   // NO
  54         body;
  55
  56 Write code like this:
  57
  58 typedef struct
  59 {
  60     int member1;
  61     char *member2;
  62 } my_structure_t;
  63
  64 void FunctionName(int argument, int arg2, int arg3, int arg4, int arg5,
  65                   int arg6, int arg7)
  66 {
  67     if (condition)
  68     {
  69         body;
  70     }
  71     else if (condition)
  72     {
  73         body;
  74     }
  75     else
  76     {
  77         body;
  78     }
  79
  80     if (very_long_condition_like_this_one_that_forces_a_line_break
  81      && other_condition)
  82     {
  83         body;
  84     }
  85
  86     switch (argument)
  87     {
  88         case FIRST:
  89             code;
  90             break;
  91
  92         case SECOND:
  93             code;
  94             break;
  95
  96         default:
  97             break;
  98     }
  99
 100     for (a=0; a<10; ++a)
 101     {
 102         loop_body;
 103     }
 104
 105     while (a < 10)
 106     {
 107         loop_body;
 108     }
 109
 110     do
 111     {
 112
 113     } while (condition);
 114 }
 115
 116 Portability
 117 ===========
 118
 119 Chocolate Doom is designed to be cross-platform and work on different
 120 Operating Systems and processors.  Bear this in mind when writing code.
 121
 122 Do not use the long type (its size differs across platforms; use
 123 int or int64_t depending on which you want).
 124
 125 Use Doom's byte data type for byte data. 'int' is assumed to be a
 126 32-bit integer, and 'short' is a 16-bit integer. You can also use the
 127 ISO C99 data types: intN_t and uintN_t where N is 8,16,32,64.
 128
 129 Be careful with platform dependencies: do not use Windows API
 130 functions, for example.  Use SDL where possible.
 131
 132 Preprocessor #defines are set that can be used to identify the OS
 133 if necessary: _WIN32 for Windows and __MACOSX__ for MacOS X. Others
 134 are set through SDL.  Try to avoid this if possible.
 135
 136 Be careful of endianness!  Doom has SHORT() and LONG() macros that
 137 do endianness conversion.  Never assume that integer types have a
 138 particular byte ordering.  Similarly, never assume that fields
 139 inside a structure are aligned in a particular way.  This is most
 140 relevant when reading or writing data to a file or a network pipe.
 141
 142 For signed integers, you shouldn't assume that (i >> n) is the same as
 143 (i / (1 << n)).  However, most processors handle bitshifts of signed
 144 integers properly, so it's not a huge problem.
 145
 146
 147 GNU GPL and licensing
 148 =====================
 149
 150 All code submitted to the project must be licensed under the GNU GPL or a
 151 compatible license.  If you use code that you haven't 100% written
 152 yourself, say so. Add a copyright header to the start of every file.  Use
 153 this template:
 154
 155 // Emacs style mode select   -*- C++ -*-
 156 //-----------------------------------------------------------------------------
 157 //
 158 // Copyright(C) YEAR Author's name
 159 //
 160 // This program is free software; you can redistribute it and/or
 161 // modify it under the terms of the GNU General Public License
 162 // as published by the Free Software Foundation; either version 2
 163 // of the License, or (at your option) any later version.
 164 //
 165 // This program is distributed in the hope that it will be useful,
 166 // but WITHOUT ANY WARRANTY; without even the implied warranty of
 167 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 168 // GNU General Public License for more details.
 169 //
 170 // You should have received a copy of the GNU General Public License
 171 // along with this program; if not, write to the Free Software
 172 // Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
 173 // 02111-1307, USA.
 174