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
  
== New code guidelines ==
+
=== Memory Management ===
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:
 
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 ===
todo.
+
* Be aware that the all Z_Zone allocated memory is freed when the WAD changes
  
==Formatting guidelines==
+
=== 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

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

External Links