CONTRIBUTING.md

   1 # DarkPlaces Contributing Guidelines
   2 -------------------------------------------------------------------------------
   3
   4 1. ### Do not break Quake or its mods, and any other game using the engine.
   5
   6    The engine has known compatibility issues with Quake and many community
   7    mods. All code must not make the situation worse. This is analogous to the policy
   8    of the Linux kernel to not break userspace.
   9
  10 2. ### Sign off all of your commits if they are to be included upstream.
  11
  12    You must use a valid, permanent email address.
  13
  14 2. ### All code submitted should follow the Allman style for the most part.
  15
  16         1. In statements, the curly brace should be placed on the next line at the
  17            same indentation level as the statement. If the statement only involves
  18            a single line, do not use curly braces.
  19
  20                 ```c
  21                 // Example:
  22                 if(foo == 1)
  23                 {
  24                         Do_Something();
  25                         Do_Something_Else();
  26                 }
  27                 else
  28                         Do_Something_Else_Else();
  29
  30                 if(bar == 1)
  31                         Do_Something_Else_Else_Else();
  32                 ```
  33
  34         2. Use tabs for indentation.
  35
  36            Use spaces subsequently for alignment of the
  37            parameters of multi-line function calls or declarations, or statements.
  38
  39                 ```c
  40                 // Example:
  41                 if(very_long_statement &&
  42                    very_long_statement_aligned &&
  43                    foo)
  44                 {
  45                         if(indented)
  46                         {
  47                                 Do_Something();
  48                                 Do_Something_Else();
  49                         }
  50                 }
  51                 ```
  52
  53         3. If possible, try to keep individual lines of code less than 100
  54            characters.
  55
  56         4. Pointer operators should be placed on the right-hand side.
  57
  58                 ```c
  59                 int foo = 1;
  60                 int *bar = &foo;
  61                 ```
  62
  63         5. Type casts should have a space between the type and the pointer.
  64
  65                 ```c
  66                 int *foo = (int *)malloc(5);
  67                 ```
  68
  69         6. Use spaces after each comma when listing parameters or variables of a
  70            struct.
  71
  72         7. Multi-line comments should be formatted like so:
  73
  74                 ```c
  75                 /*
  76                  * This is a multi-line comment.
  77                  * Sometimes, I dream about cheese.
  78                  */
  79                 ```
  80
  81            But this is okay too:
  82
  83                 ```c
  84                 /* This is another multi-line comment.
  85                  * Hiya! How are you?
  86                  */
  87                 ```
  88
  89         8. If following these guidelines in any manner would make any code less
  90            readable or harder to follow, ***ignore them***. This section is only
  91            guidelines, not rules. We're not gonna beat you over the head in pull
  92            requests because you misplaced a dereference operator.
  93
  94            For example, in some situations, placing the block on the same line as
  95            the condition would be okay because it looks cleaner:
  96
  97                 ```c
  98                 if (foo)  Do_Something();
  99                 if (bar)  Do_Something_Else();
 100                 if (far)  near();
 101                 if (boo)  AHH("!!!\n");
 102                 ```
 103
 104 4. DarkPlaces is written in the common subset of C and C++. This means it is
 105    (usually) both valid C and C++. We historically wanted to keep it that way,
 106    but don't worry about it unless you care enough and/or are a maintainer.
 107
 108    Most of the differences are caught by `-Wc++-compat` but some are subtle
 109    and would cause behavior differences between the two compilers, or are not
 110    caught by that warning. The things to look out for are:
 111
 112         1. Character constants are `int`-sized in C but `char`-sized in C++. This
 113            means `sizeof('a')` will be 4 in C, but 1 in C++.
 114
 115         2. `goto label;` cannot jump over a variable initialization. This will
 116            cause a compiler error as C++ but is not caught by `-Wc++-compat`.
 117            This is nevertheless bad code, so avoid this anyway.
 118
 119    If, for some reason, you care enough, compatibility can always be tested
 120    affirmatively by setting CC=g++. CC=clang++ may not work in the future, if
 121    it didn't already stop working in current versions of LLVM, as it otherwise
 122    spams deprecation warnings for using a C file as input to a C++ compiler.
 123
 124 > [!NOTE]
 125 > We do not officially support building C code with a C++ compiler and may not
 126 > address issue reports for buggy behavior that does not occur when compiled
 127 > with a C compiler. That said, there have been fleeting ideas for converting
 128 > either the entire engine or parts of it to C++, which is what `-Wc++-compat`
 129 > would make a little easier. So, we at least *do not discourage* such issue
 130 > reports, especially for things the warning doesn't catch. They will be noted
 131 > as they would become relevant in the event we do decide to convert to C++.