Coding Style Guide

Thus, programs must be written for people to read, and only incidentally for machines to execute.
-- Structure and Interpretation of Computer Programs

代码主要是写给人看的，而不是给机器看的，只是顺便用机器可以执行而已。
-- 《计算机程序的构造和解释》

编译器不会关心代码风格，只要语法没有错误就能编译通过。但是团队合作中编码风格至关重要，良好的代码风格有利于他人理解、修改和维护你的代码。

这里简单给出一份代码编写规范，请希望贡献代码的各位严格按照此规范编写代码。

1 程序版式

程序的版式虽然不影响功能，但影响可读性。这里的目标是编写清晰、整洁的代码，有利于他人对你的代码进行阅读、测试。

• { 与 } 各独占一行，且位于同一列，与引用它们的语句左对齐
• 函数名与其后的()之间紧挨，如 foo() 而不是 foo ()
• if、while、for 等于其后的()之间有一个空格，如 if () 而不是 if()
• 缩进使用4个空格
• 类型名与变量名之间使用1个空格分开
• 使用空行分隔程序段落
  • 在每个类声明之后加空行
  • 在每个函数定义结束之后加空行
  • 在一个函数体内，相邻两组逻辑上密切相关的语句块之间加空行
• 赋值、算术、关系、逻辑等二元运算符前后各加一空格，但一元运算符前后不加空格
• ( 向后紧跟，) , ; 向前紧跟，紧跟处不留空格
• , 与 ; 后留一个空格
• [] . -> 前后不加空格

void func1(int x, int y, int z);  // 建议的风格
void func1 (int x,int y,int z);   // 不建议的风格

if (year >= 2000)    // 建议的风格
{
    doSomething();
}

if(year>=2000){     // 不建议的风格
    doSomething();  
}

for (i = 0; i < 10; ++i)  // 建议的风格
{
    cout << i << " ";
}

for(i=0;i<10;++i){       // 不建议的风格
    cout<<i<<" ";
}

• 长代码行请分行

Director::getInstance()->getEventDispatcher()->addEventListenerWithSceneGraphPriority(contactListenner, this);

分行书写为：

Director::getInstance()->getEventDispatcher()->
        addEventListenerWithSceneGraphPriority(contactListenner, this);

if ((veryLongVar1 >= veryLongVar2) && (veryLongVar3 >= veryLongVar4))
{
    DoSomething();
}

分行书写为：

if ((veryLongVar1 >= veryLongVar2) && 
    (veryLongVar3 >= veryLongVar4))
{
    DoSomething();
}

• 修饰符 * 和 & 的位置
  • 从语义上讲，靠近数据类型更直观，但对多个变量声明时容易引起误解

int* x, y;  // 不建议的风格
int *x, y;  // 建议的风格

2 注释

写注释的原则：

• 写给自己看，理清自己的设计思路
• 写给团队成员看，使其能够接手自己的代码

请站在团队其他成员的角度书写注释。

这里规定文件、函数和类前以 Doxygen 的注释风格进行注释。

文件头注释：

/**
 * @file $FILE_BASE$.$FILE_EXT$
 * @date $DATE$
 *
 * @author XXX XXX
 * Contact: xxx@XXXX.com
 *
 * @brief
 * 
 * TODO: 
 *
 */

函数的注释：

/**
 * @brief Describe the function briefly
 * @param [in] param1 Describe the input parameter
 * @param [out] param2 Describe the output parameter
 * @return Describe the return value
 */

类的注释：

/**
 * @brief Describe the class briefly
 * @note 
 */

3 类的设计风格

• 规定使用“以行为驱动的”风格，即 public 成员在前，private 成员在后。
• 关注该类能够提供什么样的服务（接口）

class A
{
public:
    void printX()
    {
        std::cout << x << std::endl;
    }

private:
    int _x;
};

4 命名风格

总体使用“驼峰命名法”，混合使用大小写字母来构成变量和函数的名字。

• 类名首字母大写

class PlayScene
{
    /* ... */
};

• 函数、变量名首字母小写

void printName();

float homeworkScores[] = { 70.0f, 88.5f };

• 类的私有成员变量以 _ 开头

class Student
{
public:
    /* ... */

private:
    std::string _name;
    unsigned int _age;
};

5 其他

• 不要在头文件中使用 using namespace XXX，见这里
• 优先使用前缀操作符。与后缀操作符相比，前缀操作符因为无须构造临时对象而更具性能优势（尤其在使用自定义类型时）

class A; // 类名为A
A A::operator ++ ();    // 前缀操作符
A A::operator ++ (A);   // 后缀操作符，有函数参数

• 用 const 替换 #define 定义常量
• 禁止使用 malloc() 和 free()，改用 new 和 delete
• 使用 static_cast < type-id > ( expression ) 替代C语言风格的强制类型转换

double a = 3.14;

int x = (int)a;    // 不建议的风格
int x = static_cast<int>(a);  // 建议的风格