Difference between revisions of "Coding Style"

Revision as of 23:11, 30 January 2005

This article details the coding style that should be adopted when writing changes to the aMule codebase.

Formatting

Indenting

Use tabs

Always use tabs for indenting, do not use spaces. The size of each tab should be equal to 4 spaces.

Scopes

Indent inside new scopes, including classes, structs, functions, etc.

Examples:

 if ( false ) {
   ...
 } else {
   ...
 }

 class foo
 {
   foo() {
     ...
   }
 }

Whitespace

Place whitespace between brackets and keywords, and between operators and variables:

 if (something == true);

rather than

 if(something==true);

Brackets

Brackets are placed on the same line as the construct with the exception of non-inlined functions, structs and classes. Perfer the usage of brackets, even when optional, as in the case of if/while/etc blocks.

Misc

• When using the trinary operator, place brackets to promote readability.
• Add a space after the // chars when writing comments.

Documenting comments

Always remember to documment new functions and classes! Examples of documented classes can be found in can be found in CMD4Hash.h, BarShader.*, ServerListCtrl.* and others. More information on the usage and syntax of doxygen can be found in the doxygen documentation.

Use the following format, which is doxygen compatible.

Functions, classes, structs, etc

  /**
   * <Short description>
   *
   * [@param <Param_1 description>]
   * [@param <Param_n description>]
   * [@return <return value description>]
   *
   * [Long description]
   * [@see <reference to other relevant function>]
   */

Variables, typedefs, constants, etc

  //! <Description>

Coding

Naming Style

Always try to use descriptive names, except when it adds nothing to the readability, such as iterator varibles and counters (it, i, x, y, etc).

Functions

• Function names should follow the AllWordsAreUppercase convention
• Function arguments should follow the conventions for local varibles described below

Variables

• Names should follow the firstWordLowerCaseRestUpperCase convention
• Prefix global variables with g_
• Prefix static variables with s_
• Prefix member variables with m_

Classes

• Prefix classnames with C
• Names should follow the AllWordsAreUppercase convention

Constants

• Use ALLUPPERCASE names

Filenames

• For classes, use the classname without the "C" prefix.

Const correctness

Remember to mark functions and arguments (pointers, references) as const where possible. This increases the ability for us to write safer code and is a good thing.

Consts vs. Defines

Whenever possible, prefer const variables to pre-compiler defines. We've already had problems with nameclashing caused by defines, so me might as well not increase the chances of it happening again. Actual constants also has the major advantage that we gain proper type-safety.

References

Always use references where passing large datatypes suchs as wxString and CMD4Hash and only use non-const references if we are going to change the passed variables.

Hacks

Always try to avoid odd hacks and in general try to avoid abnormal stuff, assignments in if constructs and the like for instance should be avoided when possible. Also try to avoid the usage of void pointers as they result in a almost total loss of type-safety.

Helper-functions

Helper functions which can have use across the app should be placed in otherfunctions.h.

Whenever possible, prefer wxWidgets functions to system calls, as this reduces the dependencies on specific function-calls that may or may not be available on other platforms.