Changes between Version 1 and Version 2 of CodingGuidelines


Ignore:
Timestamp:
10/31/10 17:53:07 (8 years ago)
Author:
magnate
Comment:

Update for 3.1.3

Legend:

Unmodified
Added
Removed
Modified
  • CodingGuidelines

    v1 v2  
    1 This document describes what Angband code and its documentation should look like.  It is borrowed in part from the Angband Coding Guidelines by Robert Ruehlmann, Ben Harrison, and Gwidon S. Naskrent.  You may also want to read the [Angband security guide] (http://thangorodrim.net/development/security.txt). 
     1This document describes what Angband code and its documentation should look like. It is borrowed in part from the Angband Coding Guidelines by Robert Ruehlmann, Ben Harrison, and Gwidon S. Naskrent. You may also want to read the Angband security guide at http://thangorodrim.net/development/security.txt, although the default build configuration no longer uses setgid. 
    22 
    3 Use the [BSD/Allman style] (http://en.wikipedia.org/wiki/Indent_style#BSD.2FAllman_style), and indent using tabs.  Avoid lines over 80 character long (though this is not strict). 
     3Use the K&R style and indent using four spaces instead of tab. Avoid lines over 80 characters long, though this is not strict where there are multiple indents. 
    44 
    55This means: 
    66 
    7  * Curly braces for code blocks should always be on seperate lines, with the same indentation level as the previous line. 
    8  * Spaces around the mathematical, comparison, and assignment operators ('+', '-', '/', '=', '!=', '==', '>', ...).  No spaces around increment/decrement operators ('++', '--'). 
     7 * Opening braces should be on a separate line at the start of a function, but should otherwise follow the statement which requires them ('if', 'do', 'for' et al.) 
     8 * Closing braces for should be on separate lines, except where followed by 'while' or 'else' 
     9 * Spaces around the mathematical, comparison, and assignment operators ('+', '-', '/', '=', '!=', '==', '>', ...).  No spaces around  increment/decrement operators ('++', '--'). 
    910 * Spaces between C identifiers like 'if', 'while' and 'for' and the opening brackets ('if (foo)', 'while (bar)', ...). 
    10  * `do { } while ();` loops should have a newline after "do", and the "} while ();" bit should be on the same line. 
     11 * `do { } while ();` loops should have a newline after "do {", and the "} while ();" bit should be on the same line. 
    1112 * No spaces between function names and brackets and between brackets and function arguments (function(1, 2) instead of function ( 1, 2 )). 
    1213 * If you have an if statement whose conditionally executed code is only one statement, do not write both on the same line, except in the case of "break" or "continue" in loops. 
     
    1415 
    1516Example: 
    16     if (fridge) 
    17     { 
     17{{{ 
     18    if (fridge) { 
    1819      int i = 10; 
    1920 
     
    2122        bar(1, 2); 
    2223 
    23       do 
    24       { 
     24      do { 
    2525        /* Only print even numbers */ 
    2626        if (i % 2) continue; 
     
    3535      return 5; 
    3636    } 
     37}}} 
     38Also, write modern C code. Include parenthesis wherever it increases readability, and nowhere else. Always declare functions as <type> <name>(<params>). If you don't pass any parameters, make sure you write 'void' in the declaration. Use the 'const' wherever you don't modify a variable. 
    3739 
    38  
    39 Also, write modern C code.  Include parenthesis wherever it increases readability, and nowhere else.  Always declare functions in as <type> <name>(<params>).  If you don't pass any parameters, make sure you write 'void' in the declaration.  Use the 'const' wherever you don't modify a variable. 
    40  
    41 Write code for humans first and execution second.  Where code is unclear, comment, but there is no need to write such as the following: 
    42  
     40Write code for humans first and execution second. Where code is unclear, comment, but there is no need to write such as the following: 
     41{{{ 
    4342    /* Delete the object */ 
    4443    object_delete(idx); 
     44}}} 
     45It is unneccessarily verbose and hurts readability. Group code instead into ideas and comment each section of ideas. Also, use whitespace liberally to separate ideas visually. 
    4546 
    46 It is unneccessarily verbose and hurts readability.  Group code instead into ideas and comment each section of ideas.  Also, use whitespace liberally to visually seperate ideas. 
     47Each function should have a comment at its head, describing the function and including any notes on its usage, including what its various return values (if any) mean. Avoid multi-line comments in functions; instead, split the code that requires the comments into its own function or move the comment into the comment section at the top of the function. 
    4748 
    48 Each function should have a comment at its head, describing the function and including any notes on its usage, including what its various return values (if any) mean.  Avoid multi-line comments in functions; instead, split the code that requires the comments into its own function or move the comment into the comment section at the top of the function. 
     49Write code as modularly as possible. Name functions and global variables inside a module with the same prefix, like "macro_". Avoid global variables where possible, and don't expose them to the rest of the code unnecessarily. 
    4950 
    50 Write code as modularly as possible.  Name functions and global variables inside a module with the same prefix, like "macro_".  Avoid global variables where possible, and don't expose them to the rest of the code unnecessarily. 
     51If you make use of memory allocation in your module, try and make such code clean up after itself, or include it in "init" and "free" functions. Always initialise your module so it is in a known state! It is possible that the game will eventually not quit when you lose a character, but rather allow another character to be loaded or created. Unless you get things in a known state, this will cause crashes. 
    5152 
    52 If you make use of memory allocation in your module, try and make such code clean up after itself, or include it in "init" and "free" functions.  Always initialise your module so it is in a known state!  It is possible that the game will eventually not quit when you lose a character, but rather allow another character to be loaded or created.  Unless you get things in a known state, this will cause crashes. 
    53  
    54 Don't use magic numbers.  Use defines or enums (and enums where possible).  Where a constant is local, include it at the top of a file/section.  Where it is not, place it in the module's corresponding header file.  Avoid putting more things into defines.h. 
     53Don't use magic numbers. Use defines or enums (and enums where possible). Where a constant is local, include it at the top of a file/section. Where it is not, place it in the module's corresponding header file. Avoid putting more things into defines.h. 
    5554 
    5655Don't use floating point calculations. 
    5756 
    58 Code should compile cleanly as strict C89 on release and should not rely on undefined behaviour.  (Angband has, for years, been a well-defined piece of software, and no-one implements C99 fully yet.) 
     57Code should compile cleanly as strict C89 on release and should not rely on undefined behaviour. (Angband has, for years, been a well-defined piece of software, and no-one implements C99 fully yet.) There are recent moves to allow mixed declarations and code, so you may see some of those warnings in recent versions.  
    5958 
    60 Never use `strcpy()`, `strcat()`, or `sprintf()`.  Instead, use my_strcpy, my_strcat and strnfmt, which are safer and will avoid accidental trashing of memory. Similarly, avoid strncat/strncpy unless absolutely necessary, as using them is error-prone. 
     59Never use `strcpy()`, `strcat()`, or `sprintf()`. Instead, use my_strcpy, my_strcat and strnfmt, which are safer and will avoid accidental trashing of memory. Similarly, avoid strncat/strncpy unless absolutely necessary, as using them is error-prone. 
    6160 
    62 Documentation 
    63 ============= 
     61= Documentation = 
    6462 
    6563Be careful when documenting functions to use the following design: 
    66  
     64{{{ 
    6765    /** 
    6866     * Provides an example of a documentation style. 
     
    7674     */ 
    7775    bool do_something(void *example) 
    78  
     76}}} 
    7977Additional notes about the format: 
    8078 - Having the brief description separated out from the remainder of the comment means that Doxygen can pull it out without needing @brief tags. 
    8179 - Variables should be referred to with surrounding backtick ('`') quotes. 
    82  - Functions should be referred to as function_name() -- /with/ the brackets. 
     80 - Functions should be referred to as function_name() -- ''with'' the brackets. 
    8381 - In brief descriptions of classes and functions, use present tense (i.e. answer the question "What does this do?" with "It constructs / edits / calculates / returns...") 
    8482 - In long descriptions, use passive mood to refer to variables (i.e. "The variables are normalised." as opposed to "This normalises the variables.")