Development:Resource:CodeStandards
From ContactQ
Contents |
[edit] ContactQ coding conventions
Code must be written to be read, not by the compiler, but by another human being.
[edit] File naming rules
- C source file names must end in .c
- C++ source file names must end in .cpp
- Include header file names end in .h
- Filename should always be in lower case and words separated by underscores.
my_file.cpp
[edit] General rules
- All variables, comments and function names should be written in ENGLISH.
- Tabs should be used to indent the first item on each line; continuation lines should use tabs to the same level as the line being continued, with further indentation using spaces. Spaces should be used for any further formatting. Remember that as well as your favorite editor, the code may be viewed through a variety of tools, for example: ViewCVS, Doxygen and diff tools.
- Use a style consistently within a file, even it's not a preferred format; this is acceptable when reusing existing code. It will be easier to read and understand than a mixture of styles would be.
[edit] Code Comments
- All comments should be in ENGLISH.
- Comments should describe the code and not who has changed it and on what date.
- Use spaces and not tabs when aligning in-line comments. This will ensure alignment when the code is viewed in an editor set with another tab size.
- Use the Doxygen guidelines defined in this document for comments to be included in the project documentation.
- C++ may use // for end of line comments.
- Block comments should be done as follows
/*
* Block comment.
* The comment text should spaced over uniformly.
* The opening slash-star and closing star-slash are alone on a line
*/
Do NOT use block comments to remove sections of code, instead use #if 0
#if 0 /* code to hidden from the compiler */ #endif
[edit] Naming Conventions
[edit] Defines and macros
all uppercase using '_' separators.
#define MAX_COUNT 10
[edit] Variable declaration / naming
all_lowercase_with_underscores OR start with lower case followed by mixed case.
my_var myOtherVar
[edit] C Function declaration / naming
all_lowercase_with_underscores OR start with lower case followed by mixed case.
my_function() myOtherFunction()
[edit] Global constants
should be all caps with '_' separators.
const int A_GLOBAL_CONSTANT = 99;
[edit] C++
[edit] Class Names
Use either all lowercase with underscores or an initial upper case letter followed by mixed case.
e.g.
class my_class // OR class MyClass
No All Upper Case Abbreviations
[edit] Method Names
All lowercase with underscores or begin with lowercase followed by mixed case
e.g.
my_function(); // OR myFunction();
[edit] Class Attribute Names
Attribute names should be suffixed with the underscore character.
The names should follow the same rules as for class names.
e.g.
std::string buffer_;
[edit] Method Argument Names
All lowercase with underscores or lowercase followed by mixed case.
e.g.
my_class->setParam( arg_value ); // OR my_class->setParam( argValue );
[edit] Code formatting
White space should be placed around all operators.
GOOD
int x = foo + bar;
BAD
int x=foo+bar;
[edit] Function calls
Function calls and arguments should be spaced in a consistent way across the codebase. Function arguments should be presented either as: all on one line or one argument per line.
GOOD
foo(value1, value2);
foo(value1,
value2,
value3);
BAD
foo(value1,value2);
foo (value1, value2);
foo( value1, value2 );
foo(value1, value2,
value3);
[edit] Keyword layout
Keywords (if, for, while, do) should have space between the keyword and the expression used and a space immediately after the opening bracket and also immediately before the closing bracket.
GOOD
for ( x = 0; x < 5; x++ )
BAD
for(x=0;x<5;x++)
[edit] Functions
int foo( arg1, arg2 )
{
return 0;
}
[edit] If statements
if ( x == y )
{
function1();
}
else
{
function2();
}
[edit] Case statements
switch ( x )
{
case VALUE1:
function1();
break;
case VALUE2:
function2();
break;
default
function3();
break;
}
[edit] Nested statements
Never use nested statements without braces, e.g.:
GOOD
for ( x = 0; x < 5; x++ )
{
if ( foo )
{
if (bar)
funtion1();
}
}
BAD
for (x = 0; x < 5; x++ )
if ( foo )
if ( bar )
baz();
[edit] Indented code
Try to minimise the size of indented code where possible. This makes the code much more readable.
GOOD
if ( !foo )
{
result = 0;
return;
}
.... 50 lines of code ....
BAD
if ( foo )
{
/* .... 50 lines of code ... */
}
else
{
result = 0;
return;
}
[edit] C++ conventions
Always prepend std:: to identifiers that are defined in the std namespace.
The using directive should be avoided as it subverts the purpose of namespaces.
Use only the <xxx> headers, not the <xxx.h> headers.
Unlike conventional C, locals should be declared near their first use.
Don't initialize it to an "empty" value at the top of the function then "assign" it later.
[edit] Doxygen Usage Guidelines
The Qt style should be used for documentation.
Example
C++ code using the Qt style:
//! A test class.
/*!
* \class Test
* \brief A short class description.
*/
class Test
{
public:
//! An enum.
/*!> More detailed enum description. */
enum TEnum
{
TVal1, /*!< Enum value TVal1. */
TVal2, /*!< Enum value TVal2. */
TVal3 /*!< Enum value TVal3. */
}
//! Enum pointer.
/*! Details. */
*enumPtr,
//! Enum variable.
/*! Details. */
enumVar;
//! A constructor.
/*!
* A more elaborate description of the constructor.
*/
Test();
//! A destructor.
/*!
* A more elaborate description of the destructor.
*/
~Test();
//! A normal member taking two arguments and returning an integer value.
/*!
* \param a an integer argument.
* \param s a constant character pointer.
* \return The test results
* \sa Test(), ~Test(), testMeToo() and publicVar()
*/
int testMe( int a, const char *s );
//! A pure virtual member.
/*!
* \sa testMe()
* \param c1 the first argument.
* \param c2 the second argument.
*/
virtual void testMeToo( char c1, char c2 ) = 0;
//! A public variable.
/*!
* Details.
*/
int publicVar;
//! A function variable.
/*!
* Details.
*/
int (*handler)( int a, int b );
};
