C++编码标准规范.doc

1.    命名规则
1.1. 起个适当名字
1.1.1.    类名称（合用于C++）
²  类名称要能告诉咱们，这个类是什么。因而，类名称普通是名词。
²  类名字不需要告诉咱们，它从哪个类继承而来。
²  有时候加个后缀是很有用。例如类是一种代理(Agents)时，起名叫DownloadAgent更能表达真实意图。
1.1.2.    办法和函数名称（合用于C/C++）
²  办法和函数普通都要执行某种行为，因而，名称要能清晰阐明它做什么：CheckForErrors() 而不是ErrorCheck(),DumpDataToFile() 而不是 DataFile()。 这样也可以很容易区别函数和数据。
²  函数名总以动词开头，背面跟随其他名称。这样看起来更自然些。
²  可以加某些必要后缀：
Max – 表达取最大值
Cnt – 表达当前计数值
Key – 表达键值
例如：RetryMax 表达可接受最大数，RetryCnt表达当前接受数量。
²  前缀也同样有用：
Is – 用于询问某些问题。只要看到Is开头，就懂得这是一种查询。
Get – 用于获取一种值。
Set – 用于设立一种值。
例如：IsHitRetryLimit.
1.1.3.   具有度量单位名称（合用于C/C++）
²  如果一种变量用于表达时间，重量或其他度量单位，应把度量单位添加到名称中，以便开发人员更早一步发现问题。
例如：
uint32 mTimeoutMsecs;
uint32 mMyWeightLbs;
1.1.4.    缩写名称不要所有大写（合用于C/C++）
²  无论是什么缩写名称，咱们总以一种大写字母开头，背面跟随字母所有用小写。
例如：
class FluidOz;            // 而不是 FluidOZ
class NetworkAbcKey;      // 而不是 NetworkABCKey
1.2.类命名（合用于C++）
²  用大写字母作为单词分隔，每个单词首字母大写，其他字母均小写。

²  名字第一种字母应大写
²  不具有下划线 ('_')
例如：
   class NameOneTwo; 
   class Name;
1.3.类库（或程序库）命名 （合用于C/C++）
²  使用命名空间防止名字冲突。
²  如果编译器没有实现命名空间，需要用前缀来避名名字冲突，但是前缀不要过长（2个字母比较好）。
例如：
John Johnson 完毕了一种数据构造库，它可以使用JJ作为库前缀，因此类名就象下面这样：
   class JjLinkList
   {
   }
1.4.办法和函数命名（合用于C++）
²  使用与类名相似规则
例如：
   class NameOneTwo
   {
   public:
      int     DoIt();
      void    HandleError();
   }
1.5.类属性命名（合用于C++）
²  属性（普通是非公有数据成员）名字以字母'm'开头。
²  在 'm(m_)'  背面，使用与类名相似规则。
²  'm(m_)' 总是位于其他修饰符（如表达指针 'p'）前面。
例如：
   class NameOneTwo
   {
   public:
      int     VarAbc();
      int     ErrorNumber();
   private:
      int          mVarAbc;
      int          mErrorNumber;
      String*      mpName;
   }
1.6.办法和函数参数命名（合用于C++）
²  第一种字母必要小写。
²  第一种字母背面单词使用与类名相似规则。
例如：
   class NameOneTwo
   {
   public:
      int     StartYourEngines(
                               Engine&rSomeEngine,
                              Engine&rAnotherEngine);
   }
1.7.局部变量命名（合用于C/C++）
²  所有字母都用小写
²  使用下划线 '_' 作为单词分隔。
例如：
   int
  NameOneTwo::HandleError(int errorNumber)
   {
      int            error= OsErr();
      Time           time_of_error;
     ErrorProcessor error_processor;
   }
1.8.指针变量命名前缀（合用于C/C++）
²  指针变量多数状况应在前面加 'p'。
²  星号 '*' 应接近类型，而不是变量名。
例如：
  String* pName=new String;

  特别：String* pName，name；应提成两行来写：
  String* pName;
  String  name;
1.9.引用变量和返回引用函数命名前缀（合用于C++）
²  引用必要用 'r'作前缀修饰。
例如：
   class Test
   {
   public:
      void               DoSomething(StatusInfo&rStatus);

     StatusInfo&        rStatus();
      constStatusInfo&  Status() const；// 这里返回是常量引用，因此不符合本规则

   private:
     StatusInfo&        mrStatus;
   }
1.10.   全局变量命名前缀（合用于C/C++）
²  全局变量总是以 'g(g_)' 作为前缀。
例如：
    Logger g_Log;
    Logger* g_pLog;
1.11.   全局常量命名（合用于C/C++）
²  全局常量所有大写，并如下划线 '_' 分隔单词。
例如：
    const intA_GLOBAL_CONSTANT = 5;
1.12.   静态变量命名前缀（合用于C++）
²  静态变量以 's' 作为前缀。
例如：
   class Test
   {
   public:
   private:
      staticStatusInfo m_sStatus;
   }
1.13.   自定义类型（typedef）命名（合用于C/C++）
²  类型定义名称指是用typedef定义名称。
²  类型定义名称使用与类名相似规则，并使用Type作为后缀。
例如：
   typedefuint16  ModuleType;
   typedefuint32  SystemType;
1.14.   宏定义命名（合用于C/C++）
²  所有单词字母都用大写，并使用下划线 '_' 分隔.
例如：
#define MAX(a,b) blah
#define IS_ERR(err) blah
1.15.   C 函数命名（合用于C/C++）
²  C++项目中，应尽量少用C函数。
²  C函数使用GNU规范，所有字母都使用小写，并用下划线 '_' 作为单词分隔。
例如：
   int
  some_bloody_function()
   {
   }
²  特别，为了赚容C/C++，在必要时候，在C++中应如下面格式定义C函数：
   extern “C” int some_bloody_function();
²  或在C/C++中推荐使用下面格式：
   #ifdef__cplusplus__
   extern “C”{
   #endif
   int
  some_bloody_function()
   {
   }
   #ifdef__cplusplus__
   }
   #endif
1.16.   枚举命名（合用于C/C++）
²  所有字母都大写，并用下划线 '_' 作为单词分隔。
例如：
   enumPinStateType
   {
      PIN_OFF,
      PIN_ON
   };
enum { STATE_ERR, STATE_OPEN，STATE_RUNNING，STATE_DYING};
2.    排版规则
2.1. 布局和模板
2.1.1.    类布局模板 （合用于C++）
²  请使用下面模板来创立一种新类：
/**     
 * 用一行来描述类
 *
 *#include "XX.h"
 *-llib
 *
 * 类详细阐明
 * 
 * @seesomething
 */

#ifndef SORUTION_PROJECT_CLASSNAME_H
#define SORUTION_PROJECT_CLASSNAME_H

// 在这里包括系统头文献
//

// 在这里包括项目头文献
//

// 在这里包括局部头文献
//

// 在这里放置前置引用
//

class XX
{
public:
    // 类生命周期控制函数，如构造和析构，以及状态机

    /**
    *Default constructor.
    */
    XX(void);

    /**
    *Copy constructor.
    *
    *@param from The value to copy to this object.
    */
    XX(const XX& from);

    /**
    *Destructor.
    */
    virtual ~XX(void);

    // 在这里放置类运算操作符

    /**
    *Assignment operator.
    *
    *@param from THe value to assign to this object.
    *
    *@return A reference to this object.
    */
    XX&                     operator=(XX&from); 

    // 在这里放置类操作                      
    // 在这里放置属性存取
    // 在这里放置类状态查询

protected:
private:
};

// 内联办法定义
//

// 外部引用
//

#endif  // SORUTION_PROJECT_CLASSNAME_H

²  定义顺序是：public，protected，private
²  要清晰public/protected/private都应当放置哪些东西
2.1.2.   源文献格式（合用于C++）
#include "XX.h"                               // class implemented

/////////////// PUBLIC///////////////////////

//================= 构造函数 ===================

XX::XX()
{
}// XX

XX::XX(const XX&)
{
}// XX

XX::~XX()
{
}// ~XX

//=============== 操作符=========================

XX&
XX::operator=(XX&);
{
   return *this;

}// =

//==============类操作 =====================
//==============属性存取 =====================
//========状态查询   =====================
///////////// PROTECTED  //////////////////

///////////// PRIVATE    //////////////////
2.1.3.    保护头文献不被重复包括 （合用于C/C++）
²  应使用宏定义来保护头文献不被重复包括：
#ifndef SORUTION_PROJECT_CLASSNAME_H
#define SORUTION_PROJECT_CLASSNAME_H

#endif // SORUTION_PROJECT_CLASSNAME_H

²  如果使用命名空间时候，要把命名空间加到文献名前面：
#ifndef SORUTION_PROJECT_NAMESPACE_CLASSNAME_H
#define SORUTION_PROJECT_NAMESPACE_CLASSNAME_H

#endif
2.1.4.    办法和函数布局 （合用于C/C++）
²  对于有较多参数函数写法
如果参数较多，一行写不下，咱们应当提成几行来写，并且每个参数都另起一行对齐：
   int AnyMethod(
                 int  arg1, 
                 int   arg2,
                 int   arg3,
                 int   arg4)；或
int AnyMethod( int   arg1 
               , int   arg2
               , int   arg3
               , int   arg4);

2.2. 缩进、制表符以及空格 （合用于C/C++）
²  缩进时候，每一层缩进3，4，或8个空格。（推荐使用4个空格）
²  不要使用TAB，用空格，大多数编辑器可以用空格代替TAB。TAB应固定4个空格，由于大多数编辑器都是这样设立。
²  虽然没有规定缩进层次，但是4至5层是适当。如果缩进层次太多，你也许需要考虑与否进行代码重构了。
例如：
   void
   func()
   {
      if (something bad)
      {
          if (another thing bad)
          {
              while (more input)
              {
              }
          }
      }
   }
2.3. 尽量使一行不要超过78个字母 合用于C/C++）
²  有许多编辑器屏幕只有78个字母宽
2.4. 保证一行只写一条语句 （合用于C/C++）
²  一行最多只写一条语句
²  一行只定义一种变量
例如：
不要象下面这样:
char** a，*x;

int width，height；//widthand height of image

要象这样:
char** a= 0;  // 文档阐明
char*  x= 0;  // 文档阐明
2.5. 花括号 {} 规则 （合用于C/C++）
2.5.1.    花括号位置
²  在核心字下一行单独放置括号，并且与核心字对齐，如：
if condition)       
{
    ...
}
while (condition)
{
    …
}
2.5.2.    什么时候应使用花括号
所有 if，while 和 do 语句，要么用单行格式，要么使用花括号格式。
²  使用花括号格式：
if (1 == somevalue)
{
   somevalue = 2;
}
²  单行格式：
if (1 == somevalue) somevalue = 2;
或下面这样（对于这种写法，建议使用花括号）：
if (1 == somevalue)
{
somevalue = 2;
}

2.5.3.    在花括号结束位置加上注释
²  在花括号结束位置加上注释是一种好习惯。如果先后花括号距离很远，注释就能帮你理解它是如何相应。如：
while(1)
{
   if (valid)
   {

   } // if valid
   else
   {
   } // not valid

} // end forever
2.5.4.    注意屏幕大小
²  一种语句块尽量不超过一种屏幕大小，这样，不要卷动屏幕就可以阅读代码。
2.6.圆括号 () 规则 （合用于C/C++）
²  圆括号与核心字之间应放一种空格。
²  圆括号与函数名之间不要有空格。
²  Return 语句不要使用圆括号。
例如：
    if (condition)
    {
    }

    while(condition)
    {
    }

    strcpy(s，s1);

    return 1;
2.7.if else 语句格式 （合用于C/C++）
²  布局
   if (条件)               // 注释
   {
   }
   else if (条件)           // 注释
   {
   }
   else                   // 注释
   {
   }
²  条件格式
总是把常量放在等号或不等于号左边：
if ( 6 == errorNum ) ...
一种很重要理由是，如果漏写一种等号，这种写法会产生一种编译错误，有助于立即发现问题。
例如：
if ( errorNum == 6) ...
错写成：
if ( errorNum = 6) ... // 这是一种不容易发现劫难

2.8.switch 格式 （合用于C/C++）
²  直通case语句，应当放置一条注释阐明这个case语句是直通到下一种case语句。
²  总是要写default语句，不论与否是需要。
²  在case中需要定义变量时候，应把所有代码放在语句块中。
例如：
switch (...)
{
case 1:
    ...
        // 继续执行case2

case 2:
    {       
        int v;
        ...
    }
    break;

default:
}
2.9. 使用goto,continue,break 和 ?：（合用于C/C++）
2.9.1.    Goto
²  尽量避免使用Goto 语句。一种合理使用goto语句场合是，当你需要从多层循环中跳出。例如：
for (...)
{
    while (...)
    {
        ...
            if (disaster)
goto error; //跳出循环
    }
}
...
error:
clean up the mess
²  跳转标号必要单独在一行最左边。Goto语句需要有相应注释，阐明它用途。
2.9.2.    Continue and Break
²  Continue 和break 事实上起到与goto同样作用，因而，尽量少用为上。并且，Continue与break最佳不要连用。
2.9.3.    ?:
²  用括号把条件表达式括起来。
²  不要在 ?：中写上过多代码，操作表达式应尽量简洁。
²  操作语句应分行写，除非它们可以简洁放在一行当中。
例如：
   (condition) ?funct1() ：func2();
   或
   (condition)
      ?longstatement
      ：anotherlong statement;
2.10.   运算符号规则 （合用于C/C++）
²  一元操作符如（!、~ 等等）应贴近操作对象。
如：
if (!IsOk)
return ++v;
²  二元操作符如（+、*、%、== 等等）应在先后留空格。
如：
if ( v1 == v2)
     return v1 * 3;
²  ++ 和 -- 尽量使用前置运算。在C++中，不论 ++i 还是 i++，总是++i更容易生成优化代码。
如：
for(int i = 0；i < 10；++i)
2.11.    变量声明语句块 （合用于C/C++）
²  变量应当是随用随声明，不要集中在函数前（有些C语言不支持，则不在此规定之列）。特别是在for语句循环变量，应只在for语句中定义。
如：
for(int i = 0；i < 10；++i)

²  声明语句块必要要对齐
类型，变量，等号和初始化值要分别对齐。
例如：
   DWORD      mDword;
   DWORD*     mpDword;
   char*      mpChar;
   char       mChar;

   mDword     =    0;
   mpDword    =    NULL;
   mpChar      =    NULL;
   mChar      =    0;
3.    文档及注释
应当使用文档自动生成工具，来生成有关程序文档。
3.1. 文献或程序库文档注释（合用于C/C++）
可觉得整个文献编写文档。
例如：
/** @file file.h
 * Abrief file description.
 * Amore elaborated file description.
 */

3.2. 类文档注释（合用于C/C++）
在类定义前面应加上类阐明文档。
例如：
/** WindowsNT
 *  @brief Windows Nice Try.
 *  @author Bill Gates
 *  @author Several species of small furryanimals gathered together
 *          in a cave and grooving with a pict.
 *  @version 4.0
 *  @date   1996-1998
 *  @bug It crashes a lot and requires hugeamounts of memory.
 *  @bug The class introduces the more bugs，thelonger it is used.
 *  @warning This class may explode in your face.
 *  @warning If you inherit anything from thisclass，you're doomed.
 */
class WindowsNT {};

3.3. 函数文档注释（合用于C/C++）
²  函数注释
所有参数都应当有文档阐明(param)，所有返回代码都应当有文档阐明(return)，所有例外都应当有文档阐明(exception)。可以使用(see)引用关于开发资源。如：
  /**
   * 赋值操作符
   *
   *@param val 将要赋给本对象值
   *
   *@return 本对象引用
   */
  XX&  operator =(XX& val);
²  注释属性
某些自动文档工具定义属性可以包括在文档中，惯用有：
n  前提条件 (pre)
定义调用这个函数前提条件
n  警告阐明 (warning)
定义某些关于这个函数必要懂得事情。
n  备注阐明 (remarks)
定义某些关于这个函数备注信息。
n  将要完毕工作 (todo)
阐明哪些事情将在不久后来完毕
n  使用例子阐明 (example)
一种图片能表达100句话，一种好例子能解答1000个问题。
例如：
  /**
   * 复制一种字串
   *
   *@pre
   *     - 需要保证(from != 0)
   *     - 需要保证(to != 0)
   *
   *@warning
   * 缓冲区必须足够大，以便容纳下要拷贝字串。
   *
   *@example teststrcpy.cpp
   *
   *@param from 要拷贝字串
   *@param to 用于容纳字串缓冲区
   *@return void
   */
  void  strcpy(constchar* from, char* to);
3.4. Include 语句注释 （合用于C/C++）
²  如果有必要，＃include语句也应有注释，它可以告诉咱们，为什么要包括这个头文献。
3.5.语句块注释（合用于C/C++）
²  语句块注释可以用在语句块开头和结束位置：
{ 
    // Block1 (meaningful comment about Block1)
    ... some code

    { 
        // Block2 (meaningful comment about Block2)
        ... somecode
    }  // End Block2

}  // End Block1
4.    编码规定
4.1. 不要忽视编译器警告（合用于C/C++）
²  编译器警告，普通可以批示出编码存在笔误或逻辑错误。因而，不能轻视编译器任何警告。对的作法是，不容许代码在编译时产生任何警告信息。
4.2. 应使用源代码管理器（合用于C/C++）
²  依照开发规模，选取适当源代码管理器。使用源代码管理器是非常必要。
4.3. 固有类办法成员（合用于C++）
²  默认构造函数(DefaultConstructor)
如果构造函数所有参数都是可选，那么这个构造函数也是默认构造函数。如果没有定义任何普通构造函数，则编译将自动生成一种。
²  虚析构函数(Virtual Destructor)
如果一种类可以被继承，那么应当使用虚析构函数。如果没有定义虚析构函数，则编译器将自动生成一种。
²  拷贝构造函数(Copy Constructor)
如果一种类不应当被拷贝，应当定义一种私有拷贝构造函数，并且不定义它实现。如果不懂得一种类与否应当被拷贝，就以为它是不可拷贝，直到你确认它应当被拷贝。如果没有定义拷贝构造函数，则编译器将自动生成一种。
²  赋值操作(AssignmentOperator)
如果一种类不应当被赋值，应当定义一种私有赋值操作函数，并且不定义它实现。如果不懂得一种类与否应当被赋值，就以为它是不可赋值，直到你确认它应当被赋值。如果没有定义赋值操作函数，则编译器将自动生成一种。
4.4. 使用命名空间 （合用于C++）
²  命名规则
根名字普通是设计者名字。例如公司名称等等。
²  不要在全局空间使用using语句。
4.5. 初始化所有变量 （合用于C/C++）
²  无论如何，都要初始化所有变量。咱们无法保证编译器会给个什么样初值。
4.6. 保持函数短小精悍（合用于C/C++）
²  普通状况下，一种函数最佳在一种屏幕内，不要超过三个屏幕。
4.7.对空语句进行注释 （合用于C/C++）
²  For和while语句如果跟随一种空语句，需要对此语句进行注释，并且空语句应另起一行。如：
   while(*dest++ = *src++)
      ;         // VOID
²  不容许写成：
   while (*dest++ = *src++) ;   // 绝对不容许这样写

4.8. 不要用if语句默认办法测试非零值（合用于C/C++）
²  If语句只用于检测布尔值(bool)，不要用默认办法测试非零值，例如：
建议使用：
   if (FAIL != f())
不建议使用下面表达式：
   if (f())

²  宏定义状况也同样：
   #define STREQ(a,b) (strcmp((a)，(b)) == 0)
或者使用内联函数：
   inline bool
  StringEqual(char* a，char* b)
   {
      (strcmp(a，b)== 0) ?return true ：return false;
       Or more compactly:
      returnstrcmp(a，b) == 0;
   }
4.9.布尔类型 （合用于C/C++）
²  初期C++没有布尔类型，但新C++原则增长了布尔类型。如果可以使用内置布尔类型状况下，应使用布尔类型。

初期布尔类型定义为：
   typedef int     bool;
   #defineTRUE    1
   #defineFALSE   0

或：
   const intTRUE  = 1;
   const int FALSE= 0;

²  在这种状况下，条件表达式不要比较1值(如TRUE，YES等等)，而要用0值(如FALSE,NO等等)进行比较。由于多数函数返回0表达FALSE，而非零表达TRUE。如：
   if (TRUE ==func()) { ... // 错误：如果func()返回 2 怎么办？
必要写成：
   if (FALSE !=func()) { ...
4.10.   避免在语句中内含赋值 （合用于C/C++）
²  只有一种状况可以在语句中内含赋值，它要能使代码显得更易理解，例如：
   while (EOF != (c= getchar()))
   {
      process thecharacter
   }
²  ++ 和 -- 操作也是一种赋值语句
²  内含赋值语句经常会带来某些副作用。在遇到这种状况时，咱们应提成几种语句来写。例如：
   a = b + c;
   d = a + r;
不应当写成：
   d = (a = b + c)+ r;
4.11.   对的使用Const （合用于C/C++）
²  C/C++ 提供const 核心字，用于批示不应当被修改对象或数据。对的使用Const既可以提供编译器优化批示，也可以避免某些编码错误。
4.12.    不要在头文献定义数据（合用于C/C++）
不要把数据定义放在头文献，如：
/*
 * aheader.h
 */
int x = 0;
4.13.   不要直接使用数字 （合用于C/C++）
²  直接使用数字，会使源代码难以理解和维护。如：
if      (22 ==foo)    { start_thermo_nuclear_war()；}
else if (19 == foo)    {refund_lotso_money()；}
else if (16 == foo)    {infinite_loop()；}
else                   { cry_cause_im_lost()；}
当一段时间过去后来，有谁会记得22和19是什么意思？如果数字变化，或者是编写错误，更是难以发现问题。
²  咱们可以用#define或者常量来变化这一状况，如：
#define  PRESIDENT_WENT_CRAZY  (22)
const int WE_GOOFED= 19;
enum
{
    THEY_DIDNT_PAY=16
};

if (PRESIDENT_WENT_CRAZY    == foo) { start_thermo_nuclear_war()；}
else if (WE_GOOFED          == foo)  {refund_lotso_money()；}
else if (THEY_DIDNT_PAY     == foo) { infinite_loop();}
else                                 {happy_days_i_know_why_im_here()；}

4.14.    宏（合用于C/C++）
²  如果可以，使用内联函数代替宏。
例如：
#ifndef MAX
#define  MAX(x,y)  (((x) > (y) ?(x) ：(y))    // 取最大数
#endif
使用内联函数可以达到相似效果，并且更安全：
   inline int
   max(int x，inty)
   {
      return (x> y ?x ：y);
   }
²  要注意副作用
必要小心副作用，由于在调用表达式时，会发生潜在错误。
例如：
   MAX(f(x),z++);
²  表达式总是用括号括起来
在宏展开时，使用括号可以避免宏展开后产生二义性。
例如：
#define ADD(x,y) x + y
必要写成：
#define ADD(x,y) ((x) + (y))
²  保证宏名称唯一性
和全局变量同样，宏也会与其他名称产生冲突。下面两条规则有助于解决这个问题：
n  在宏名称前加上库名字
避免使用简朴而惯用名字，如：MAX 和MIN