Hacking:Code style conventions: Difference between revisions
Created page Code style conventions. |
|||
Line 2: | Line 2: | ||
=== General === |
=== General === |
||
Use space instead real tabs that equal 4 spaces. |
|||
Max length of source code line equal 120 characters. Put "//---" cars in front of function definitions with maximum length (120) : |
Max length of source code line equal 120 characters. Put "//---" cars in front of function definitions with maximum length (120) : |
||
Line 10: | Line 8: | ||
//--------------------------------------------------------------------------------------------------------------------- |
//--------------------------------------------------------------------------------------------------------------------- |
||
</source> |
</source> |
||
==== Indentation ==== |
|||
Use spaces, not tabs. 4 spaces instead one real tab. Tabs should only appear in files that require them for semantic meaning, like Makefiles. |
|||
A case label should be indented with its switch statement. The case statement is indented too. |
|||
<source lang="cpp"> |
|||
switch (condition) |
|||
{ |
|||
case fooCondition: |
|||
case barCondition: |
|||
i++; |
|||
break; |
|||
default: |
|||
i--; |
|||
} |
|||
</source> |
|||
==== Spacing ==== |
|||
Do not place spaces around unary operators. |
|||
<code>i++;</code> |
|||
Do place spaces around binary and ternary operators. |
|||
<source lang="cpp"> |
|||
y = m * x + b; |
|||
f(a, b); |
|||
c = a | b; |
|||
return condition ? 1 : 0; |
|||
</source> |
|||
Do not place spaces before comma and semicolon. |
|||
<source lang="cpp"> |
|||
for (int i = 0; i < 10; ++i) |
|||
{ |
|||
doSomething(); |
|||
} |
|||
f(a, b); |
|||
</source> |
|||
Place spaces between control statements and their parentheses. |
|||
<source lang="cpp"> |
|||
if (condition) |
|||
{ |
|||
doIt(); |
|||
} |
|||
</source> |
|||
Do not place spaces between a function and its parentheses, or between a parenthesis and its content. |
|||
<source lang="cpp"> |
|||
f(a, b); |
|||
</source> |
|||
==== Line breaking ==== |
|||
Each statement should get its own line. |
|||
<source lang="cpp"> |
|||
x++; |
|||
y++; |
|||
if (condition) |
|||
{ |
|||
doIt(); |
|||
} |
|||
</source> |
|||
==== Braces ==== |
|||
Use typically trailing braces everywhere (if, else, functions, structures, typedefs, class definitions, etc.) |
Use typically trailing braces everywhere (if, else, functions, structures, typedefs, class definitions, etc.) |
||
Line 31: | Line 94: | ||
</source> |
</source> |
||
==== Null ==== |
|||
In C++, the null pointer value should be written as <code>nullptr</code>. In C, it should be written as <code>NULL</code>. |
|||
==== Floating point literals ==== |
|||
Unless required in order to force floating point math, do not append <code>.0</code>, <code>.f</code> and <code>.0f</code> to floating point literals. |
|||
<source lang="cpp"> |
|||
const double duration = 60; |
|||
void setDiameter(float diameter) |
|||
{ |
|||
radius = diameter / 2; |
|||
} |
|||
setDiameter(10); |
|||
const int framesPerSecond = 12; |
|||
double frameDuration = 1.0 / framesPerSecond; |
|||
</source> |
|||
==== Names ==== |
|||
Function names start with an upper case: |
Function names start with an upper case: |
||
<source lang="cpp"> |
<source lang="cpp"> |
||
Line 36: | Line 119: | ||
</source> |
</source> |
||
In multi-word function names each word starts with an upper case: |
In multi-word function names each word starts with an upper case, including all letters in an acronym: |
||
<source lang="cpp"> |
<source lang="cpp"> |
||
void ThisFunctionDoesSomething(void); |
void ThisFunctionDoesSomething(void); |
||
void HTMLDocument; |
|||
</source> |
</source> |
||
Line 59: | Line 143: | ||
<source lang="cpp"> |
<source lang="cpp"> |
||
#define SIDE_FRONT 0 |
#define SIDE_FRONT 0 |
||
</source> |
|||
Use full words, except in the rare case where an abbreviation would be more canonical and easier to understand. |
|||
<source lang="cpp"> |
|||
size_t characterSize; |
|||
size_t length; |
|||
short tabIndex; // more canonical |
|||
</source> |
|||
Data members in C++ classes should be private. Static data members should be prefixed by “s_”. Other data members should be prefixed by “m_”. |
|||
<source lang="cpp"> |
|||
class String |
|||
{ |
|||
public: |
|||
... |
|||
private: |
|||
short m_length; |
|||
}; |
|||
</source> |
</source> |
||
Line 75: | Line 178: | ||
int const *p; |
int const *p; |
||
</source> |
</source> |
||
Precede boolean values with words like “is” and “did”. |
|||
<source lang="cpp"> |
|||
bool isValid; |
|||
bool didSendData; |
|||
</source> |
|||
Precede getters that return values through out arguments with the word “get”. |
|||
<source lang="cpp"> |
|||
void getInlineBoxAndOffset(InlineBox*&, int& caretOffset) const; |
|||
</source> |
|||
Use descriptive verbs in function names. |
|||
<source lang="cpp"> |
|||
bool convertToASCII(short*, size_t); |
|||
</source> |
|||
Prefer <code>const</code> to <code>#define</code>. Prefer inline functions to macros. |
|||
Macros that expand to function calls or other non-constant computation: these should be named like functions, and should have parentheses at the end, even if they take no arguments (with the exception of some special macros like ASSERT). Note that usually it is preferable to use an inline function in such cases instead of a macro. |
|||
<code>#define</code>, <code>#ifdef</code> “header guards” should be named exactly the same as the file (including case), replacing the <code>.</code> with a <code>_</code>. |
|||
<source lang="cpp"> |
|||
// mainwindowsnogui.h |
|||
#ifndef MAINWINDOWSNOGUI_H |
|||
#define MAINWINDOWSNOGUI_H |
|||
</source> |
|||
=== Other Punctuation === |
|||
Negation operator should not be used in its short form : |
Negation operator should not be used in its short form : |
Revision as of 20:33, 26 March 2016
Code style conventions
General
Max length of source code line equal 120 characters. Put "//---" cars in front of function definitions with maximum length (120) :
//---------------------------------------------------------------------------------------------------------------------
Indentation
Use spaces, not tabs. 4 spaces instead one real tab. Tabs should only appear in files that require them for semantic meaning, like Makefiles.
A case label should be indented with its switch statement. The case statement is indented too.
switch (condition)
{
case fooCondition:
case barCondition:
i++;
break;
default:
i--;
}
Spacing
Do not place spaces around unary operators.
i++;
Do place spaces around binary and ternary operators.
y = m * x + b;
f(a, b);
c = a | b;
return condition ? 1 : 0;
Do not place spaces before comma and semicolon.
for (int i = 0; i < 10; ++i)
{
doSomething();
}
f(a, b);
Place spaces between control statements and their parentheses.
if (condition)
{
doIt();
}
Do not place spaces between a function and its parentheses, or between a parenthesis and its content.
f(a, b);
Line breaking
Each statement should get its own line.
x++;
y++;
if (condition)
{
doIt();
}
Braces
Use typically trailing braces everywhere (if, else, functions, structures, typedefs, class definitions, etc.)
if (x)
{
//code
}
The else statement starts on new line after the last closing brace.
if (x)
{
//code
}
else
{
//code
}
Null
In C++, the null pointer value should be written as nullptr
. In C, it should be written as NULL
.
Floating point literals
Unless required in order to force floating point math, do not append .0
, .f
and .0f
to floating point literals.
const double duration = 60;
void setDiameter(float diameter)
{
radius = diameter / 2;
}
setDiameter(10);
const int framesPerSecond = 12;
double frameDuration = 1.0 / framesPerSecond;
Names
Function names start with an upper case:
void Function(void);
In multi-word function names each word starts with an upper case, including all letters in an acronym:
void ThisFunctionDoesSomething(void);
void HTMLDocument;
Variable names start with a lower case character.
float x;
In multi-word variable names the first word starts with a lower case character and each successive word starts with an upper case.
float maxDistanceFromPlane;
Names of recursive functions end with "_r"
void WalkBSP_r( int node );
Defined names use all upper case characters. Multiple words are separated with an underscore.
#define SIDE_FRONT 0
Use full words, except in the rare case where an abbreviation would be more canonical and easier to understand.
size_t characterSize;
size_t length;
short tabIndex; // more canonical
Data members in C++ classes should be private. Static data members should be prefixed by “s_”. Other data members should be prefixed by “m_”.
class String
{
public:
...
private:
short m_length;
};
Use ‘const’ as much as possible. Use:
const int *p; // pointer to const int
int * const p; // const pointer to int
const int * const p; // const pointer to const int
Same true for variables that will not be changed after initialization.
Don’t use:
int const *p;
Precede boolean values with words like “is” and “did”.
bool isValid;
bool didSendData;
Precede getters that return values through out arguments with the word “get”.
void getInlineBoxAndOffset(InlineBox*&, int& caretOffset) const;
Use descriptive verbs in function names.
bool convertToASCII(short*, size_t);
Prefer const
to #define
. Prefer inline functions to macros.
Macros that expand to function calls or other non-constant computation: these should be named like functions, and should have parentheses at the end, even if they take no arguments (with the exception of some special macros like ASSERT). Note that usually it is preferable to use an inline function in such cases instead of a macro.
#define
, #ifdef
“header guards” should be named exactly the same as the file (including case), replacing the .
with a _
.
// mainwindowsnogui.h
#ifndef MAINWINDOWSNOGUI_H
#define MAINWINDOWSNOGUI_H
Other Punctuation
Negation operator should not be used in its short form :
if (!cond) // error-prone
if (cond == false) // better
if (not cond) // better (alternative keyword, recommended way)
Put spaces between function arguments in definition or call :
int function(int a, int b)
{
called_function(a, b);
}
Don't use
using namespace MyNamespace
C++ namespaces and the using namespace MyNamespace
statement can confuse lupdate. It will interpret VClass::tr
like MyNamespace::VClass::tr
. Runtime translation of these strings will fail because of that.
Classes
Class names start with "V" and each successive word starts with an upper case.
class VArc;
Class variables have the same naming convention as variables.
class VArc
{
qreal f1;
QString formulaF1;
qreal f2;
QString formulaF2;
qreal radius;
QString formulaRadius;
VPointF center;
}
Class methods have the same naming convention as functions.
class VArc
{
QPointF CutArc (const qreal &length, VArc &arc1, VArc &arc2) const;
}
Indent the names of class variables and class methods to make nice columns. The variable type or method return type is in the first column and the variable name or method name is in the second column.
class VVec3
{
float x;
float y;
float z;
float Length(void) const;
const float * ToFloatPtr(void) const;
}
The * of the pointer is in the first column because it improves readability when considered part of the type.
Ordering of class variables and methods should be as follows:
- list of friend classes
- public variables
- public methods
- protected variables
- protected methods
- private variables
- private methods
This allows the public interface to be easily found at the beginning of the class.
Always make class methods ‘const’ when they do not modify any class variables.
Avoid use of ‘const_cast’. When object is needed to be modified, but only const versions are accessible, create a function that clearly gives an editable version of the object. This keeps the control of the ‘const-ness’ in the hands of the object and not the user.
Function overloading should be avoided in most cases. For example, instead of:
const idAnim * GetAnim( int index ) const;
const idAnim * GetAnim( const char *name ) const;
const idAnim * GetAnim( float randomDiversity ) const;
Use:
const idAnim * GetAnimByIndex( int index ) const;
const idAnim * GetAnimByName( const char *name ) const;
const idAnim * GetRandomAnim( float randomDiversity ) const;
Inline member functions define outside the class:
class Foo
{
public:
void method(); // best practice: don't put the inline keyword here
...
};
inline void Foo::method() // best practice: put the inline keyword here
{
// code
}
Note. Don't make virtual methods inline. See Clang warning -Wweak-vtables. Discusion on StackOverflow.
File names
Each class should be in a separate source file unless it makes sense to group several smaller classes. The file name should be the same as the name of the class with the "V" prefix.
class VArc;
files:
varc.cpp
varc.h