HACKING.md 6.24 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40
# Coding style guidelines

The coding style guidelines for Chocolate Doom are designed to keep the
style of the original source code.  This maintains consistency throughout
the program, and does not require the original code to be changed. Some
of these guidelines are stricter than what was done in the original
source; follow these when writing new code only: there is no need to
change existing code to fit them.

You should set tabs to *display* as eight spaces, not four.  However,
*indentation* should be four spaces.  If possible, do not use tab
characters at all.  There is a utility called “expand” which will remove
tab characters.  For the reasoning behind this, see:
http://www.jwz.org/doc/tabs-vs-spaces.html

Please write code to an 80 column limit so that it fits within a standard
80 column terminal. Do not leave trailing whitespace at the end of lines.

Functions should be named like this: `AB_FunctionName`.  The `AB` prefix
denotes the subsystem (`AM_` for automap, `G_` for game, etc).  If a
function is static, you can omit the prefix and just name it like
`FunctionName`.  Functions and global variables should always be made
static if possible.

Put `_t` on the end of types created with typedef.  Type names like this
should be all lowercase and have the subsystem name at the start. An
example of this is `txt_window_t`.  When creating structures, always
typedef them.

Do not use Hungarian notation.

Do not use the goto statement.

Use C++-style comments, ie. `//` comments, not `/* ... */` comments.
I don’t care that this isn’t standard ANSI C.

Variables should be named like this: `my_variable_name`, not like this:
`MyVariableName`.  In pointer variable declarations, place the `*` next
to the variable name, not the type.

41 42 43
When casting variables from one type to another, put a space after the
last closing brace.

44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219
When using an if, do, while, or for statement, always use the { } braces
even when they are not necessary.  For example, do this:

```c
if (condition)
{
    body;
}
```

Not this:

```c
if (condition)   // NO
    body;
```

Write code like this:

```c
typedef struct
{
    int member1;
    char *member2;
} my_structure_t;

void FunctionName(int argument, int arg2, int arg3, int arg4, int arg5,
                  int arg6, int arg7)
{
    int assign_var;

    assign_var = arg2 + arg3 * arg4 * (arg5 + arg6);

    if (foo && !bar || baz && qux || !(foo && bar && baz))
    {
        body;
    }
    else if (xyz + 4 < abc * 4 + 3)
    {
        body;
    }
    else
    {
        body;
    }

    if (very_long_condition_like_this_one_that_forces_a_line_break
     && other_condition)
    {
        body;
    }

    switch (argument)
    {
        case FIRST:
            code;
            break;

        case SECOND:
            code;
            break;

        default:
            break;
    }

    for (a = 0; a < 10; ++a)
    {
        FunctionCall(arg1, arg2, arg3, arg4,
                     arg_split_onto_second_line);
    }

    while (a < 10)
    {
        loop_body;
    }

    do
    {

    } while (condition);
}
```

## Security

The C standard library has a number of unsafe functions that should be
avoided when writing code for Chocolate Doom. These are:

Unsafe function   |   Safer alternative
------------------|------------------------
`gets()`          |  `fgets(.., stdin)`
`sprintf`         |  `M_snprintf()`
`snprintf`        |  `M_snprintf()`
`vsprintf`        |  `M_vsnprintf()`
`vsnprintf`       |  `M_vsnprintf()`
`strcpy()`        |  `M_StringCopy()`
`strncpy()`       |  `M_StringCopy()`
`strcat()`        |  `M_StringConcat()`
`strncat()`       |  `M_StringConcat()`
`strdup()`        |  `M_StringDuplicate()`
`realloc()`       |  `I_Realloc()`

Lots of the code includes calls to DEH_String() to simulate string
replacement by the Dehacked tool. Be careful when using Dehacked
replacements of printf format strings. For example, do not do this:

```c
printf(DEH_String("foo %s"), s);
sprintf(mybuf, DEH_String("bar %s"), t);
```

Instead do this:

```c
DEH_printf("foo %s", s);
DEH_snprintf(mybuf, sizeof(mybuf), "bar %s", t);
```

This does the format string replacement safely in a way that checks
the arguments securely.

## Portability

Chocolate Doom is designed to be cross-platform and work on different
Operating Systems and processors.  Bear this in mind when writing code.

Do not use the `long` type (its size differs across platforms; use
`int` or `int64_t` depending on which you want).

Use Doom’s byte data type for byte data. `int` is assumed to be a
32-bit integer, and `short` is a 16-bit integer. You can also use the
ISO C99 data types: `intN_t` and `uintN_t` where N is 8, 16, 32, 64.

Be careful with platform dependencies: do not use Windows API
functions, for example.  Use SDL where possible.

Preprocessor `#defines` are set that can be used to identify the OS
if necessary: `_WIN32` for Windows and `__MACOSX__` for Mac OS X. Others
are set through SDL.  Try to avoid this if possible.

Be careful of endianness!  Doom has `SHORT()` and `LONG()` macros that
do endianness conversion.  Never assume that integer types have a
particular byte ordering.  Similarly, never assume that fields
inside a structure are aligned in a particular way.  This is most
relevant when reading or writing data to a file or a network pipe.

For signed integers, you shouldn’t assume that `(i >> n)` is the same as
`(i / (1 << n))`.  However, most processors handle bitshifts of signed
integers properly, so it’s not a huge problem.

## GNU GPL and licensing

All code submitted to the project must be licensed under the GNU GPLv2 or a
compatible license.  If you use code that you haven’t 100% written
yourself, say so. Add a copyright header to the start of every file.  Use
this template:

```
//
// Copyright(C) YEAR Author's name
//
// This program is free software; you can redistribute it and/or
// modify it under the terms of the GNU General Public License
// as published by the Free Software Foundation; either version 2
// of the License, or (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
//
// *File description goes here*
//
```