Shadowrun: Awakened Forums Welcome, Guest. Please login or register.
Did you miss your activation email?

Login with username, password and session length
 
  Site Forums   Wiki   Bugs Tasks Code Docs Help Register Login  
    Page   Discussion         View source History  

Coding Standard

From Shadowrun: Awakened

Jump to: navigation, search

This coding standard is meant to make the style of the code more homogenous and therefore more maintainable. Files submitted to the project must adhere to them or they will be bounced back to the author with a link to this wiki page.

Contents

Conventions

The following are the code conventions for our code in Shadowrun Awakened. They are meant to blend with the coding style of our third party libraries.

Variables

  • lowerCamelCase (localCountVariable)
  • Member variables start with a "_" (_memberCountVariable)

Functions

  • Member functions should be lowerCamelCase (setListenerPos, getLocalPose)
  • Global & Static function should be UpperCamelCase
  • Try to use 'set' and 'get' appropriately

Classes

  • Names should be UpperCamelCase (PhysicalObject, Simulation)
  • Pure abstract base classes should start with an 'I' (IType)

Namespaces

  • The name of a .lib is also the namespace for all of its code
  • Names should be UpperCamelCase (SraSimulation, SraEditor)
  • DO NOT PLACE "using" statements in .h files
  • Classes and code in Support.lib do not need a namespace

Files

  • Files should be named for their containing class
  • Header files (.h) go into 'Include' directories
  • Code files (.cpp) go into 'Src' directories
  • Resist the urge to place many class definition inside a single file (multiple pure abstract "interface" classes in the .h of the class which utilizes it is ok).

Commenting

We will be using Doxygen to generate automatic documentation for our code. Please comment each class (in its .h declaration) and function (in its .cpp implementation) with as much detail as necessary. When maintaining code, if a comment is false or no longer needed, delete it.

Doxygen allows many formats for comments, but we prefer to use the most simple for C++. Use a triple-slash (///) to serve as the "Detailed Description" in the documentation:

///
/// Comment text
/// More comment text
///

Comments inside code, which are not picked up by Doxygen, should tend toward verbosity. Remember, your code is an example to future developers and they will need to know what is does. Areas with math concepts (etc) should have comments on the concept as well as the structure of the code. Expect developers to use Doxygen to find useful code, but in-code comments to understand it.

Best Practices

There are a few techniques that contributors to the project are encouraged to utilize. They are things everyone knows they should do, but do not always hold themselves to doing. So do them!

  • Try to use scoping to manage memory as much as possible
    • If you meed to allocate memory with "new" try managing it with an std::auto_ptr, then you can still use scoping to manage the memory NOTE: std::auto_ptr should NOT be used for dynamic arrays.
    • Try to manage memory of class member variables using scoping class instead of using pointers. If you must use a pointer, try using an std::auto_ptr as the member variable.
  • If you are creating a basic accessor or mutator for a class that only returns or sets a single member variable without any other work, consider using the GET or SET macros in the file "CodeGenMacros.h" in Support.lib. They take the function's intended name, the data type, and the member variable as arguments then generates an accessor or mutator in-place.
  • If you feel compelled to write a new Macro, ensure that it will cause the compiler to issue type-safety errors when used improperly. Type safety is one of the biggest reasons to NOT use a macro, so if yours does not create code which will enforce it, then consider writing a function instead.
  • When overloading a function, try to ensure only one version contains the 'real' implementation and all others just call that one version with modified arguments.
    • When you think you need to overload, consider using a default argument instead
  • Visual Studio Users: If you feel ready to commit changes, try compiling and running under the 'Release' configuration. Does it work?

Sponsored Links