Changes between Version 3 and Version 4 of CodingGuidelines


Ignore:
Timestamp:
11/01/10 13:56:39 (9 years ago)
Author:
takkaria
Comment:

Make rules more concise.

Legend:

Unmodified
Added
Removed
Modified
  • CodingGuidelines

    v3 v4  
    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 at http://thangorodrim.net/development/security.txt, although the default build configuration no longer uses setgid. 
     1This document describes what Angband code and its documentation should look like. 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 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. 
     3Rules: 
     4* K&R brace style, with four spaces per indent 
     5* Avoid lines over 80 characters long (not strict if there are multiple indents, but ideally they should be refactored) 
     6* If a function takes no parameters, it should be declared as function(void), not just as function(). 
     7* Use const where you shouldn't be modifying a variable. 
     8* Avoid global variables like the plague, we already have too many. 
     9* Use enums where possible instead of defines, and never use magic numbers. 
     10* Don't use floating point. 
     11* Code should compile as C89 and not rely on undefined behaviour. 
     12* Don't use the C built-in string functions, use the my_ versions instead (strcpy -> my_strcpy, sprintf -> strnfmt()).  They are safer. 
    413 
    5 This means: 
    6  
     14Our indent style is: 
    715 * 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.) 
    816 * Closing braces for should be on separate lines, except where followed by 'while' or 'else' 
    917 * Spaces around the mathematical, comparison, and assignment operators ('+', '-', '/', '=', '!=', '==', '>', ...).  No spaces around  increment/decrement operators ('++', '--'). 
    10  * Spaces between C identifiers like 'if', 'while' and 'for' and the opening brackets ('if (foo)', 'while (bar)', ...). 
     18 * Spaces between C identifiers like 'if', 'while' and 'for' and the opening brackets ('if (foo)', 'while (bar)', ...), 
    1119 * `do { } while ();` loops should have a newline after "do {", and the "} while ();" bit should be on the same line. 
    1220 * No spaces between function names and brackets and between brackets and function arguments (function(1, 2) instead of function ( 1, 2 )). 
    1321 * 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. 
    1422 * `return` does not use brackets, `sizeof` does. 
     23 * Use two indents when a functional call/conditional extends over multiple lines, not spaces. 
    1524 
    1625Example: 
    1726{{{ 
    1827    if (fridge) { 
    19       int i = 10; 
     28        int i = 10; 
    2029 
    21       if (foo > sizeof(int)) 
    22         bar(1, 2); 
     30        if (i > 100) { 
     31            i += randint0(4); 
     32            bar(1, 2); 
     33        } else { 
     34            foo(buf, sizeof(buf), FLAG_UNUSED, FLAG_TIMED, 
     35                    FLAG_DEAD); 
     36        } 
     37       
     38        do { 
     39            /* Only print even numbers */ 
     40            if (i % 2) continue; 
    2341 
    24       do { 
    25         /* Only print even numbers */ 
    26         if (i % 2) continue; 
     42            /* Be clever */ 
     43            printf("Aha!"); 
     44        } while (i--); 
    2745 
    28         /* Be clever */ 
    29         printf("Aha!"); 
    30       } while (i--); 
    31  
    32       p++; 
    33       x += 4; 
    34  
    35       return 5; 
     46        return 5; 
    3647    } 
    3748}}} 
    38 Also, 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. 
    3949 
    4050Write code for humans first and execution second. Where code is unclear, comment, but e.g. the following is unneccessarily verbose and hurts readability: 
     
    4454}}} 
    4555 
    46 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. 
     56= Code modules = 
    4757 
    48 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. 
    49  
    50 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. 
    51  
    52 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/externs.h. 
    53  
    54 Don't use floating point calculations. 
    55  
    56 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.) There are recent moves to allow mixed declarations and code, so you may see some of those warnings in recent versions.  
    57  
    58 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. 
     58* You should write code as modules wherever possible, with functions and global variables inside a module with the same prefix, like "macro_". 
     59* If you need to initialise stuff in your module, include "init" and "free" functions and call them appropriately rather than putting module-specific stuff all over the place. 
     60* One day the game might not quit when a game ends, and might allow loading other games.  Keep this in mind. 
    5961 
    6062= Documentation =