Difference between revisions of "Coding standard"
From OdaWiki
(New code guidelines) |
|||
| Line 10: | Line 10: | ||
==Code guidelines== | ==Code guidelines== | ||
| − | + | === General === | |
* Add a [[test]] for every change (or an explanation of why this is impossible) | * Add a [[test]] for every change (or an explanation of why this is impossible) | ||
| Line 23: | Line 23: | ||
* goto | * goto | ||
| − | == | + | === Memory Management === |
| − | + | ||
| − | + | ||
| − | + | ||
If you need to use malloc(), calloc(), realloc(), free() functions. Use the '''macros''' located in '''m_alloc.h''', these are provided because they are much better when it comes to debugging code and such: | If you need to use malloc(), calloc(), realloc(), free() functions. Use the '''macros''' located in '''m_alloc.h''', these are provided because they are much better when it comes to debugging code and such: | ||
| Line 41: | Line 38: | ||
=== Z_Zone Memory Management === | === Z_Zone Memory Management === | ||
| − | + | * Be aware that the all Z_Zone allocated memory is freed when the WAD changes | |
| − | ==Formatting | + | === Formatting === |
* If creating a new file, include a GPL header at the top of it, as seen in other files. | * If creating a new file, include a GPL header at the top of it, as seen in other files. | ||
| Line 58: | Line 55: | ||
* Defensive and secure coding practices | * Defensive and secure coding practices | ||
* Maintain traditional naming conventions, for consistency | * Maintain traditional naming conventions, for consistency | ||
| − | |||
| − | |||
==External Links== | ==External Links== | ||
* [http://www.jwz.org/doc/tabs-vs-spaces.html tabs-vs-spaces] | * [http://www.jwz.org/doc/tabs-vs-spaces.html tabs-vs-spaces] | ||
Revision as of 19:28, 3 June 2008
Contents
Overview
Odamex relies on a coding standard to ensure continuity, this reduces bugs and provides easy readability of the code.
Requirements
- Make logical changes in separate patches
- Minimise the number of changes in each patch
- Provide an off switch for every new feature
- Do not submit things you cannot test (e.g. code for alternative platforms)
Code guidelines
General
- Add a test for every change (or an explanation of why this is impossible)
Things you should definitely AVOID in your code:
- Changing code that already works
- Precompiler macros
- Global variables (they can create problems elsewhere in code)
- Variants (tagged unions) - they can present a performance problem
- Magic numbers (use #define or const in your code for fixed numbers, at the top of files)
- Hungarian notation (just plan evil)
- C style strings. (replace them with C++ types where it is safe to do so)
- goto
Memory Management
If you need to use malloc(), calloc(), realloc(), free() functions. Use the macros located in m_alloc.h, these are provided because they are much better when it comes to debugging code and such:
- M_Malloc(size_t Size)
- M_Calloc(size_t Items, size_t Size)
- M_Realloc(void *Pointer, size_t Size)
- M_Free(uintptr_t &Reference)
A list of features these functions offer:
- The Size value can NEVER be 0, this prevents platform-specific behaviour.
- M_Free uses a reference instead of a pointer, it still does the same as normal free(), but will NULL the address on return.
- They will abort the program if their operation fails.
Z_Zone Memory Management
- Be aware that the all Z_Zone allocated memory is freed when the WAD changes
Formatting
- If creating a new file, include a GPL header at the top of it, as seen in other files.
- Descriptive comments
- Comments of reasonable size. (not too big and not too small)
- Comment formatting. (in c/c++, either // for 1 liners or /* */ for multiple lines)
- Indentations to be of 1 tab character, using 4 space width tabs
- Be sure your editor/IDE's EOL mode is LF, not CRLF or CR
- 80 line character limit, for devs with text-based editors
- if you can, limit functions to a maximum size (like the amount that would fit on a monitor with a reasonable screen resolution)
What you should strive for:
- Clarity of code
- Defensive and secure coding practices
- Maintain traditional naming conventions, for consistency