Date post: | 26-Mar-2015 |
Category: |
Documents |
Upload: | aaliyah-faulkner |
View: | 215 times |
Download: | 1 times |
Con
fide
ntia
l©
200
8 T
elec
a A
B
QT coding conventions
Author: Johnny Liu
Date: July 14, 2010
Version: 1.0
Teleca Chengdu
Con
fide
ntia
l©
200
8 T
elec
a A
B
2
Have two parts about Qt coding convention
1.The official parts
2.Our defined parts(We defined this parts according to C++ coding convention)
Con
fide
ntia
l©
200
8 T
elec
a A
B
3
QT coding conventions
1. The official parts
Con
fide
ntia
l©
200
8 T
elec
a A
B
4
Indentation
4 spaces are used for indentation
Spaces, not tabs!
Con
fide
ntia
l©
200
8 T
elec
a A
B
5
Declaring variables
Declare each variable on a separate line
Avoid short (e.g. “a”, “rbarr”, “nughdeget”) names whenever possible
Single character variable names are only okay for counters and temporaries, where the purpose of the variable is obvious. E.g.
for (int i = 0 ; i < 100; ++i)
Wait with declaring a variable until it is needed
// Wrong
int a;
char *c;
// Correct
int iHeight
char *pchNameOfThis;
Con
fide
ntia
l©
200
8 T
elec
a A
B
6
Declaring variables
Variables and functions start with a small letter. Each consecive word in a variable’sname starts with a capital letter
//Wrong
Int IBookNumber;
// Correct
Int iBookNumber;
Avoid abbreviations
// Wrong
short Cntr;
// Correct
short shCounter;
Con
fide
ntia
l©
200
8 T
elec
a A
B
7
Whitespace
Use blank lines to group statements together where suited
Always use only one blank line
Always use a single space after a keyword, and before a curly brace.
// Wrong
if(foo){
}
// Correct
if (foo) {
}
Con
fide
ntia
l©
200
8 T
elec
a A
B
8
Whitespace
For pointers or references, always use a single space between the type and ‘*’ or ‘&’, but no space between the ‘*’ or ‘&’ and the variable name.
char *x;
const QString &strMyString;
No space after a cast.
Avoid C-style casts when possible.
// Wrong
char* pchBlockOfMemory = (char* ) malloc(data.size());
// Correct
char *pchBlockOfMemory = (char *)malloc(data.size());
char *pchBlockOfMemory = reinterpret_cast<char *>(malloc(data.size()));
Con
fide
ntia
l©
200
8 T
elec
a A
B
9
Braces
As a base rule, the left curly brace goes on the same line as the start of the statement:
// Wrong
if (a>b)
{
}
// Correct
if (a>b) {
}
Con
fide
ntia
l©
200
8 T
elec
a A
B
10
Braces
Exception: Function implementations and class declarations always have the left brace on the start of a line:
static void foo(int g)
{
qDebug("foo: %i", g);
}
class Moo
{
};
Con
fide
ntia
l©
200
8 T
elec
a A
B
11
Braces
Use curly braces when the body of a conditional statement contains more than one line, and also if a single line statement is somewhat complex.
// Wrong
if (address.isEmpty()) {
return false;
}
// Correct
if (address.isEmpty())
return false;
Con
fide
ntia
l©
200
8 T
elec
a A
B
12
Braces
Exception 1: Use braces also if the parent statement covers several lines / wraps
// Correct
if (address.isEmpty() || !isValid()
|| !codec) {
return false;
}
Con
fide
ntia
l©
200
8 T
elec
a A
B
13
BracesException 2: Use braces also in if-then-else blocks where either the if-code or the
else-code covers several lines
// Wrong
if (address.isEmpty())
return false;
else {
qDebug("%s", qPrintable(address));
++it;
}
// Correct
if (address.isEmpty()) {
return false;
} else {
qDebug("%s", qPrintable(address));
++it;
}
Con
fide
ntia
l©
200
8 T
elec
a A
B
14
Braces// Wrong
if (a)
if (b)
...
else
...
// Correct
if (a) {
if (b)
...
else
...
}
Con
fide
ntia
l©
200
8 T
elec
a A
B
15
Braces
Use curly braces when the body of a conditional statement is empty
// Wrong
while (a);
// Correct
while (a) {}
Con
fide
ntia
l©
200
8 T
elec
a A
B
16
Parentheses
Use parentheses to group expressions:
// Wrong
if (a && b || c)
// Correct
if ((a && b) || c)
// Wrong
a + b & c
// Correct
(a + b) & c
Con
fide
ntia
l©
200
8 T
elec
a A
B
17
Switch statementsThe case labels are on the same column as the switch
Every case must have a break (or return) statement at the end or a comment to indicate that there’s intentionally no break. E.g.
switch (myEnum) {
case Value1:
doSomething();
break;
case Value2:
doSomethingElse();
break;
default:
defaultHandling();
break;
}
Con
fide
ntia
l©
200
8 T
elec
a A
B
18
Line breaksKeep lines shorter than 100 characters; insert breaks if necessary.
Commas go at the end of a broken line; operators start at the beginning of the new line. The operator is at the end of the line to avoid having to scroll if your editor is too narrow.
// Wrong
if (longExpression +
otherLongExpression +
otherOtherLongExpression) {
}
// Correct
if (longExpression
+ otherLongExpression
+ otherOtherLongExpression) {
}
Con
fide
ntia
l©
200
8 T
elec
a A
B
19
General exception
Feel free to break a rule if it makes your code look bad.
Notes:
The attachment is the official “Qt Coding Convention” and “QtFw for S60 coding conventions”, those documents are very important, please check it.
Official QT coding conventions.zip
Con
fide
ntia
l©
200
8 T
elec
a A
B
20
Qt Coding Convention
2.Our defined parts(We defined this parts according to C++ coding
convention)
Con
fide
ntia
l©
200
8 T
elec
a A
B
21
Add file and version information
At the beginning of header files and .cpp files, need to use comment make simple notes about Copyright, Function description ,Version, Author,ect. Function description is a little more important, we often simplify it over or forget to update when some big changes are made.
/ *********************************************************************
* Copyright(c)2010 Teleca company. * All rights reserved * * Name: filename.h/ filename.cpp
* Description: Brief description files contents and features.
* * Version: 1.0
* Author: Johnny Liu
* Date: July 14, 2010
************************************************************************/
Con
fide
ntia
l©
200
8 T
elec
a A
B
22
Function header comment: Features, Parameters and Return value
E.g:
/********************************************************
* Function: Briefly describe the features of function
* Parameters: param1——Description;* param2——Description;* param3——Description;* Return value: Briefly describe the return value
********************************************************/
Con
fide
ntia
l©
200
8 T
elec
a A
B
23
Variables definition and comment
1)The definition of variables use Hungarian notation (The compound words or phrases in which the elements are joined without spaces, the first letter is low case and the abbreviation of variable category, the words behind are all start with upper case). The name should use “Prefix + Noun” or “Prefix + Adj. + Noun”. E.g.
float fValue;
int iOldValue;
QString strNewValue;
Important variables are need additional comments, because the name of variables usually can’t show what it is completely, it need to tell developers more information.
Con
fide
ntia
l©
200
8 T
elec
a A
B
24
Variables definition and comment
The details of Hungarian notation please check the this attachment.
2)The common controls variable name use the Hungarian notation with controls abbreviation together. E.g.
QGroupBox *pGboxReceive;
QLabel *pLblName;
QPushButton *pPbtnSend;
The usual controls abbreviation are in this attachment.
Hungarian notation.rar
Usual Control Abbreviation.rar
Con
fide
ntia
l©
200
8 T
elec
a A
B
25
Variables definition and comment
3)Global variables and class data members use long name, local variables use short name. The name of class data members beginning with m_, static variables beginning with s_, global variables beginning with g_.
The prefix of class data members start with m_(‘m’ means member) can avoid confuse with another kinds of variables. E.g.
Class Square
{
private:
int m_iWidth; //Data member
int m_iHeight; //Data member
}
Con
fide
ntia
l©
200
8 T
elec
a A
B
26
Variables definition and comment
The prefix of static variables is s_(‘s’means static), E.g.
void init(…)
{
static int s_iInitValue; // static variables
…
}
If we have to use global variables, the prefix of it is g_ (means global), E.g.
int g_iHowManyPeople; // global variables
int g_iHowMuchMoney; // global variables
Notes: We should try to avoid use global variables as we can.
Con
fide
ntia
l©
200
8 T
elec
a A
B
27
Variables definition and comment
4)Local variables should simple and easy to understand, use common variables, E.g. nCount , strName, ect.
5)In programs, if two or more classes have same abbreviation.e.g. QToolBar and QToolButton, both abbreviation are tb. Then we need to change the abbreviation in one of them, the change principle is avoid conflict and can express the mean of classes. e.g. The abbreviation of QToolBar can be change to ‘tbar’, but QToolButton still use ‘tb’ for arrreviation.
6) Class name starts with the combination of words that all beginning with upper case, but the function name use camel case style. E.g.
class Node; // class name
class LeafNode; // class name
void drawRect(void); // function name
void setValue(int value); // function name
The camel case style document is in this attachment. CamelCase.rar
Con
fide
ntia
l©
200
8 T
elec
a A
B
28
Header files structure and class declaration arrangement
1) The header files consist with three parts.
<1>The version declaration at the beginning of header files.( Reference the first rule ) .
<2> Preprocessing block.(e.g. The header files start with(#ifndef***, #define***) , end with(#endif //***).
<3>Function and class declaration, ect.
Con
fide
ntia
l©
200
8 T
elec
a A
B
29
Header files structure and class declaration arrangement2)In class declaration, the order is: Q_OBJECT-> public-> siganls->
slots->protected-> priavte. If need to declaration some another data types(Structure,Enumerate,etc.), should put those declaration before the class declaration.
If in same classes, both data variables and function declaration are use same type declaration , split both of them. E.g.
private : void addAll(); … private : int m_iNum; … 3)At usual, if we use the Signals/Slots, the first sentence of class
declaration is Q_OBJECT.
Con
fide
ntia
l©
200
8 T
elec
a A
B
30
UI layout principle
1)When make Qt UI, use QLayout as more as you can for layout management, try to avoid use absolute coordinates, unless you are certain that the UI won’t changed it’s coordinate forever.
2)If one area have many widgets, try to put those widgets in a window box(e.g. QWidget, QFrame,QGroupBox,etc.), then put those window boxes in the UI.
Con
fide
ntia
l©
200
8 T
elec
a A
B
31
Debug information
At first, in order to debug our program, we should add debug information in our codes. We should define a macro wrapped by QT_NO_DEBUG_OUTPUT in *.h file, E.g.
#ifndef QT_NO_DEBUG_OUTPUT
#define PRINT(s) qDebug(s)
#else
#define PRINT(s)
#endif // QT_NO_DEBUG_OUTPUT
Con
fide
ntia
l©
200
8 T
elec
a A
B
32
Enums and Constants
Name of Enums and Constants are use upper case beginning words compounds.
E.g.
1) enum SwitchStateType
{
SwitchOn,
SwitchOff
};
2)enum { StateError, StateOpen, StateRunning, StateClose};
3) const int NumberOfMaxVolume;
4)const int TopSectionHeight
Con
fide
ntia
l©
200
8 T
elec
a A
B
The End
Author: Johnny Liu
Date: July 14, 2010
Version: 1.0