[[AxisCPPProjectPages]]

This is the proposed coding convention for Axis C++ project.

The coding convention is based on the Apache Developers' C Language Style Guide

A Coding Convention for Axis C++ Code

Revision 0.0 2004/03/30 by Samisa Abeysinghe: initial draft

Revision 0.1 2004/04/01 by Damitha: Fix {} conflict, Added long line breaking and doxygen commenting guidelines

Revision 0.2 2004/04/01 by Samisa Abeysinghe: Did some visual formatting

== Purpose == ex: To enhance readability and maintainability of Axis C++ code.

Definitions

Member functions are functions that are associated with C++ classes.
Data members are variables that are part of classes.

Identifier Names

All constant identifiers are all capitals. Multiple words separated with '_' character (e.g. MAXIMUM_LINE_LENGTH)
All variable identifiers follow the formatscope_prefix_[storage_prefix][type_prefix]IdentifierName (e.g. g_pcMyName)
- Scope Prefixes
  - g_ - Global
  - m_ - Data memeber
  - (default local has no prefix)
- Storage Prefixes
  - p - pointer (Ex: int* piVar, char* pcVar)
  - s - static (Global static - gs_, Member static ms_ and Local static s_. Ex: int gs_iGlobalVar)
  - r - references (Ex: int& riVar)
- Type Prefixes
  - u - unsigned (Ex: unsigned int uiVar, unsigned long ulVar)
  - i - int (Ex: int iVar)
  - c - char (Ex: char cVar)
  - l - long (Ex: long lVar)
  - s - short (Ex: short sVar)
  - f - float (Ex: float fVar)
  - d - double (Ex: double dVar)
  - b - bool (Ex: bool bVar)
  - str - string (NOTE: char* is denoted by pc and NOT str; str is used for string class objects)
All variable identifiers begin with a lowercase letter with the first letter of words other than first word capitalized. In case there is a prefix, first letter of the first word too will be capitalized. (e.g. count, rowCount, m_pcName)
Global variables begin with g_ (e.g. g_Name).
Class data members begin with m_ (e.g. m_pcBuffer)
Static data members begin with m_st (e.g, m_stiClientCount).
Both member and non-member functions begin with a lowercase letter with second word onwards the first letter capitalized (e.g. getName, parse, setFile).
Names of classes begin with an uppercase letter with first letter of each word capitalized (e.g. Axis, AxisConfig).
Abbriviations should be in capitals (e.g. SOAP, WSDD and NOT Soap or Wsdd)

Pointers and References

Pointers - * should be closer to the type (Ex: int* piVar, int** ppiVar)
References - & should be closer to the type (Ex: int& riVar)

Indentation, General Style

Each level of indentation of code is four spaces. Tab characters should never be used.
For class declarations and functions the curlybraces should be placed as follows

{{{ ClassName/methodName { //statements; }

}}}
For contol structures

{{{ ControlStructureSyntax { //statements }

}}}
Specific indentation rules for function declarations and control-flow keywords are given below.

Class Declarations

Classes are declared in the following order: public member functions, protected member functions, private member functions, protected data members, and private data members. It is advisable not to declare any public data members. Constructors should be on the top of the member function list, followedby destructor and finally the other member functions. e.g:

 class SOAPApplication 
{
public:
{{{    SOAPApplication(); 
    ~SOAPApplication(); 
    void run(); 
    int parseMessage( char * pcMessage );

protected: void trackSession(); private: int m_iRequestCount; };

}}}

Control Structures

The control structures are as follows:

if (expression) 
{
{{{    statements;

} else { statements; }

for (expression; expression; expression) { statements; }

do { statements; } while (expression);

while (expression) { statements; }

switch (expression) { case constant: {{{ statements;

break; }}}

default: {{{ statements;

break; }}}

}

}}}

Expressions

Space before and after assignment and other and operators. No space between unary operators (increment, decrement, and negation) and the lvalue. Examples:

    a = b 
    a + b 
    a < b 
    a = -b 
    a = !b 
    ++a

Statements

Function calls

No spaces allowed between function name and starting bracket
No spaces allowed between starting bracket and first argument
One space should be kept between arguments

Ex: MyMethod(type arg1, type2 arg2);

Comparisons against constants

Constant should come first
One space should be kept in both sides of the operator

Ex: if (AXIS_SUCCESS != iStatus)

Checking pointers

Should avoid == and != operators

Ex: "if (pPointer == NULL)" should be avoided and instead "if (pPointer)" should be used.

Long lines

Number of columns in a line should be <= 80. If a line exceeds this, it should be taken into the next line after breaking in a proper place. The break point could be a space or any other special symbol used in the language. Next line starts with four spaces indented.

    if ((LOBYTE(wsaData.wVersion) < WS_VERSION_MAJOR()) || 
        (LOBYTE(wsaData.wVersion) == WS_VERSION_MAJOR() && 
         HIBYTE (wsaData.wVersion) < WS_VERSION_MINOR())) 
    {

Comments

/*
{{{ * long comments which need more than one line use 
 * this block comment style, for both C and C++ 
 */

statement; short C comments statement; // short C++ comments

}}}

Doxygen commenting conventions as described in the following link is suggested. Note that Axis C++ already use this convention in the existing code.

URL: http://www.nbirn.net/Resources/Developers/Conventions/Commenting/C_Comments.htm#Documenting

File Names

C++ source files use the suffix .cpp. C++ header files use the suffix .h
Files corresponding to a class must have the same name as the class name.
Files should have the copyright notice in the header commnets.
After the copyright notice, the rivition history should be there
- Format of Rivision note:

    Revision rivision_no date by author_full_name 
    Short description of the update done

References

Apache Developers' C Language Style Guide - URL:http://www.apache.org/dev/styleguide.html

Doxygen commenting syntax - URL: http://www.nbirn.net/Resources/Developers/Conventions/Commenting/C_Comments.htm#Documenting

Coding%Convention