DEVEL/code_style.txt

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