DEVEL/code_style.txt

   1 NetHack DevTeam Coding Style
   2 ============================
   3
   4 NetHack is written in C, with a little bit of C++ to access platform
   5 libraries. This coding style document is concerned primarily with the style
   6 used for C source files. We do not have a defined style for C++ files, but C++
   7 should be styled in keeping with C.
   8
   9 The code base in C files was, close to the 3.6 release, reformatted using a
  10 version of the clang-format tool patched to support K&R-style argument
  11 declarations. Due to some incompatibilities, the patch is not publicly
  12 available and clang-format is not expected to be regularly used.
  13
  14 Developers should do their best to adhere to the coding style to promote
  15 legibile, easy-to-edit code. Legibility is paramount, so in some cases, it may
  16 be better not to fully adhere to the style guidelines.
  17
  18 Recipes for common text editors can be found at the end of this file.
  19
  20 Indentation and Spacing
  21 -----------------------
  22
  23 The basic indentation is 4 spaces wide. All indentation is done using space
  24 characters, not tabs.
  25
  26 Lines should be at most 78 characters wide. If a line would be longer than the
  27 limit, the line should be wrapped and the wrapped portion should be aligned
  28 with the parentheses or brackets containing the wrap. If there is no set of
  29 parenthese or brackets, the line should be indented four spaces. Wrapping
  30 should normally occur after a comma or before a binary operator, when
  31 possible:
  32
  33     int index
  34         = SomeExcessivelyLongExpression;
  35
  36     fcall(arg1,
  37           arg2, (cond13
  38                  && cond2));
  39
  40 Single blank lines should be used wherever convenient to improve readability.
  41
  42 Functions and Control Satements
  43 -------------------------------
  44
  45 For a function definition, the return type, declarator, and opening brace
  46 should each appear on a line of their own. Arguments are never declared in the
  47 function declarator, but are declared, unintended, K&R-style before the
  48 opening brace:
  49
  50     void
  51     foo(i, c)
  52     int i;
  53     char c;
  54     {
  55         /* function body */
  56     }
  57
  58 Opening braces of control statements appear on the same line as the control
  59 statement:
  60
  61     if (condition) {
  62         /* body */
  63     }
  64
  65 Else statements and the while statements of do-while blocks appear on the same
  66 line as the closing brace of the if or do statement. Otherwise, closing braces
  67 always get a line of their own.
  68
  69     if (condition) {
  70         /* body */
  71     } else if (condition) {
  72         do {
  73             /* body */
  74         } while (condition);
  75     } else {
  76         /* body */
  77     }
  78
  79 If a control block has only a single statement, it can appear on a line of its
  80 own, with an indent. If the statement is a null statement, then it should be
  81 expressed as an empty set block, not with a semicolon, because many compilers
  82 will warn if a null statement is used:
  83
  84     if (condition)
  85         fcall();
  86
  87     if (condition) {
  88     } else
  89         fcall();
  90
  91 If multiple control blocks are being used in a row, it may be more readable to
  92 use braces even for single statements, and they should be used if they improve
  93 readability. The following is an example of poor usage:
  94
  95     if (condition) {
  96         /* long body */
  97     } else if (condition)
  98         statement;
  99     else {
 100         /* very long body */
 101     }
 102
 103 Switch statements should have the case labels unindented, and the statements
 104 should be indented normally. The default case should occur last unless there's
 105 a compelling reason not to, and fallthroughs should be explicitly marked as
 106 such with a comment, to avoid Yeenoghu getting the touch of death again:
 107
 108     switch (condition) {
 109     case FOO:
 110     case BAR:
 111         fcall();
 112         /* fall-through */
 113     case BAZ:
 114         fcall();
 115         break;
 116
 117     default:
 118         statement;
 119     }
 120
 121 Variables should never be declared in a condition or a for loop
 122 initialization, and if an assignment is used as a condition, it should be
 123 wrapped in an additional set of parentheses for clarity:
 124
 125     int *p;
 126     if ((p = fcall())) {
 127         /* body */
 128     }
 129
 130     int i;
 131     for (i = 1; i < 10; ++i) {
 132         /* body */
 133     }
 134
 135 Spaces in Expressions
 136 ---------------------
 137
 138 Spaces should appear around binary operators, after commas, after a C-style
 139 cast, and after the keyword in a control statement. They should not appear
 140 between a function name and the opening parenthesis of a function call, nor
 141 immediately inside a pair of parentheses:
 142
 143     foo(i, j, l);
 144     if ((boolean) condition) {
 145         /* body */
 146     }
 147
 148 Vim Configuration
 149 =================
 150
 151 For vim, the following settings are encouraged when editing NetHack code, to
 152 ensure that indentation is done correctly:
 153
 154     set shiftwidth=4
 155     set softtabstop=4
 156     set expandtab
 157     set tabstop=4
 158     set shiftround
 159     set textwidth=78
 160     set cindent
 161     set filetype=c
 162
 163
 164 Visual Studio Configuration
 165 ===========================
 166
 167 In Visual Studio under Tools->Options->Text Editor->C/C++, you can set the
 168 following options to obtain desired behavior:
 169
 170 [Tabs]
 171 Indenting: Smart
 172 Tab size: 4
 173 Indent size: 4
 174 Insert Spaces
 175
 176 There are a number of other options under [Formatting] that should be
 177 checked (Indentation, New Lines, Spacing, and Wrapping), but there are so
 178 many entries that reproducing them here is impractical. Fortunately, the
 179 options are in plain English, so walking through them with a copy of
 180 this Guide handy and making changes as required will suffice.
 181
 182 emacs Configuration
 183 ===================
 184
 185 There are no doubt umpteen different ways to handle this in emacs.
 186 Putting the following in ~/.emacs.el is one
 187
 188 (defun hook-c ()
 189   (setq c-set-style "k&r")
 190   (setq c-basic-offset 4)
 191   (setq indent-tabs-mode nil)
 192   (c-set-offset 'knr-argdecl-intro 0))
 193 (add-hook 'c-mode-common-hook 'hook-c)
 194