Standard Templates - Heartbroken-Git/Project_Blood_Bowl GitHub Wiki

Programming

Language: English

Indentation type: K&R style

funct(param){
  working
}

namespace std: keep namespace std, but put std:: before each cout, cin, endl.

Pointers: use smart pointers (shared_ptr, auto_ptr, scoped_ptr)

License: WTFPL (DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE version 2)

Miscellaneous:

Use ++i instead of i++

Private attributes starts with lower case and ends with _, for example: attributeExample_

Constants written entirely in upper case, for example: CONSTANTEXAMPLE

Documentation

Doxygen software used to automate the production of the documentation. In order to produce the same documentation at all times these writing standards for the Doxygen comments are to be followed :

File documentation

Must be placed at the header of every source file (except if license terms require the license to go first in which case it should immediately follow it).

/**
 * @file 
 * @copyright 
 * @author 
 * @date 
 * @brief 
 */

@file must be followed by the filename (including its extension)
@copyright must be followed by the abbreviation (eg. WTFPL v2, GPL-3.0...) of the license that encompasses the file
@author must be followed by the author of the file, should there be several authors add one line @author per author
@date must be followed by the date of the last revision to the file
@brief must be followed by a short description of the intent of the file

Methods/Functions documentation

Must be placed before the documented method.

/**
 * @brief 
 * @details
 * @author 
 * @param 
 * @pre 
 * @post
 * @return
 */

@brief must be followed by a short description of the purpose of the method
@details (optional) can be placed to give a longer and more accurate description of the workings of the method
@author (semi-optional) must be placed and followed by the author of the method should the file have several authors
@param (semi-optional) must be placed and followed by the parameter name and then by a description of what the parameter is (eg. @param c character used as an example here)
@pre (optional) can be used to indicate the preconditions surrounding the method's parameter
@post (optional) can be used to indicate the postconditions surrounding the method's returned value
@return (semi-optional) must be used to describe the value returned by the method should it return one

Class documentation

Must be placed before the documented class.

/**
 * @class 
 * @brief 
 * @details 
 * @author
 */

@class must be followed by the class's name
@brief must be followed by a short description of the purpose of the class
@details (optional) can be used to give a longer description of the uses of the class
@author (semi-optional) must be placed and followed by the author of the class should the file have several authors

Notes, remarks and other comments on documentation

Purely optional fields that can be added to Doxygen comments field to provide particular comments or insights on what follows.

/**
 * @attention
 * @bug
 * @example
 * @note 
 * @remark
 * @sa
 * @todo
 */

@attention can be used to bring to the attention of the user a particular information
@bug (should be avoided) can be used to warn the user of a particular bug plaguing the documented code, use GitHub's issues tracker instead
@example can be used to provide an example of use of the documented code
@note can be used to add a note related to the documented code such as its temporal complexity
@remark can be used to give an insightful remark to the user about the workings of the documented code
@sa can be used to link some documented code to some other code and explain how they are related
@todo (should be avoided) can be used to provide a list of features to be added to the documented code, use the todo list available on GitHub's issues tracker