Difference between revisions of "Coding standard"
From OdaWiki
(→Requirements) |
(New code guidelines) |
||
| Line 22: | Line 22: | ||
* C style strings. (replace them with C++ types where it is safe to do so) | * C style strings. (replace them with C++ types where it is safe to do so) | ||
* goto | * goto | ||
| + | |||
| + | == New code guidelines == | ||
| + | These apply when writing brand new code in Odamex, whether it be patches or other. | ||
| + | |||
| + | === Standard 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 === | ||
| + | todo. | ||
==Formatting guidelines== | ==Formatting guidelines== | ||
Revision as of 11:53, 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
- 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
New code guidelines
These apply when writing brand new code in Odamex, whether it be patches or other.
Standard 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
todo.
Formatting guidelines
- 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