第一章 布局和风格
第一节 基本规则
【条款1-1-1 】 良好布局的目标是准确表现代码的逻辑结构,始终如一地表现代码的逻辑结构和改善代码可读性。
第二节 单条语句的布局
【条款1-2-1 】变量定义前后必须加空行。
示例:如下例子不符合规范。
UINT nTotal = 0;
UINT nNumber = 0;
for (UINT i = 0; i < MAX_ITEMS; i++)
{
nTotal = GetMoney();
nNumber = GetNumber();
... // other program code
}
应如下书写:
//注意此处要空行
UINT nTotal = 0;
UINT nNumber = 0;
//注意此处要空行
for (UINT i = 0; i < MAX_ITEMS; i++)
{
nTotal = GetMoney();
nNumber = GetNumber();
... // other program code
}
【条款1-2-2-3 】在布尔比较表达式中常量应放左边
if (NEDPR_MORE_PACKETS == nExtractPacketResult
|| NEDPR_JUST_A_PACKET == nExtractPacketResult)
【条款1-2-4 】尽量以const取代#define
#define USER_NUMBER_MAX 1024
替换为:
Const UINT USER_NUMBER_MAX = 1024;
【条款1-2-5 】具名常量和枚举常量应该用大写
范例:
Const UINT USER_NUMBER_MAX = 1024;
enum SSIDE_SESSION_TYEP
{
SSIDE_ST_CTRL = 1,
SSIDE_ST_DATA = 2
};
【条款1-2-6 】较长的语句(>80字符)要分成多行书写,长表达式要在低优先级操作符处划分新行,操作符放在新行之首,划分出的新行要进行适当的缩进,使排版整齐,语句可读。
示例:
bResult = (NEDPR_MORE_PACKETS == nExtractPacketResult
|| NEDPR_JUST_A_PACKET == nExtractPacketResult);
【条款1-9 】循环、判断等语句中若有较长的表达式或语句,则要进行适应的划分,长表达式要在低优先级操作符处划分新行,操作符放在新行之首。
示例:
if ((nTaskNumber < MAX_ACT_TASK_NUMBER)
&& (IsValidStatItem (nStatItem)))
{
... // program code
}
for (i = 0, j = 0; (i < ArrBufferKeyword[nWordIndex].nWordLength)
&& (j < objNewKeyword.nWordLength); i++, j++)
{
... // program code
}
for (i = 0, j = 0;
(i < FIRST_WORD_LENGTH) && (j < SECOND_WORD_LENGTH);
i++, j++)
{
... // program code
}
【条款1-2-7 】一行只写一条语句。
不符合规范示例1。
objObjObjRect.nLength= 0; objObjRect.nNWidth = 0;
应如下书写
objObjRect.nLength= 0;
objObjRect.nNWidth = 0;
不符合规范示例2,C++没有定义表达式的运算顺序,也没有定义子程序参数的求值顺序,所有编译器在第一个参数的或前或后来计算第二个参数n+2,结果是不确定的,不同的编译器有不同的结果
PrintMessage(++n, n + 2);
应如下书写
++n;
PrintMessage(n, n + 2);
不符合规范示例3
void Strcpy(char* pszS1,char* pszS2)
{
while(*++pszS1= *++pszS2);
}
应如下书写
void Strcpy(char* pszS1,char* pszS2)
{
do
{
++pszS1;
++pszS2;
*pszS1 = *pszS2;
}while(0 != *pszS1 );
}
【条款1-2-8 】对齐只使用空格键,不使用TAB键。
说明:以免用不同的编辑器阅读程序时,因TAB键所设置的空格数目不同而造成程序布局不整齐,不要使用BC作为编辑器合版本,因为BC会自动将8个空格变为一个TAB键,因此使用BC合入的版本大多会将缩进变乱。
【条款1-2-9 】在两个以上的关键字、变量、常量进行对等操作时,它们之间的操作符之前、之后或者前后要加空格;进行非对等操作时,如果是关系密切的立即操作符(如->),后不应加空格。
说明:采用这种松散方式编写代码的目的是使代码更加清晰。
由于留空格所产生的清晰性是相对的,所以,在已经非常清晰的语句中没有必要再留空格,如果语句已足够清晰则括号内侧(即左括号后面和右括号前面)不需要加空格,多重括号间不必加空格,因为在C/C++语言中括号已经是最清晰的标志了。
在长语句中,如果需要加的空格非常多,那么应该保持整体清晰,而在局部不加空格。给操作符留空格时不要连续留两个以上空格。
示例:
(1) 逗号、分号只在后面加空格。
int a, b, c;
(2)比较操作符, 赋值操作符"="、 “+=”,算术操作符"+"、"%",逻辑操作符"&&"、"&",位域操作符"<<"、"^"等双目操作符的前后加空格。
if (nCurrentTime >= MAX_TIME_VALUE)
a = b + c;
a *= 2;
a = b ^ 2;
(3)"!"、"~"、"++"、"–"、"&"(地址运算符)等单目操作符前后不加空格。
*p = 'a'; // 内容操作"*"与内容之间
flag = !isEmpty; // 非操作"!"与内容之间
p = &mem; // 地址操作"&" 与内容之间
i++; // "++","--"与内容之间
(4)"->"、"."前后不加空格。
p->id = pid; // "->"指针前后不加空格
(5) if、for、while、switch等与后面的括号间应加空格,使if等关键字更为突出、明显。
if (a >= b && c > d)
第三节 控制块的布局
【条款1-3-1 】程序块要采用缩进风格编写,缩进的空格数为4个。
说明:对于由开发工具自动生成的代码可以有不一致。
【条款1-3-2 】if、for、do、while、case、switch、default等语句自占一行,且if、for、do、while等语句的执行语句部分无论多少都要加括号{}。
示例:如下例子不符合规范。
if (NULL == pUserCR) return;
应如下书写:
if NULL == pUserCR)
{
return;
}
【条款1-3-3 】程序块的分界符(如C/C++语言的大括号‘{’和‘}’)应各独占一行并且位于同一列,同时与引用它们的语句左对齐。在函数体的开始、类的定义、结构的定义、枚举的定义以及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。
示例:如下例子不符合规范。
for (...) {
... // program code
}
if (...)
{
... // program code
}
void ExampleFunction( void )
{
... // program code
}
应如下书写。
for (...)
{
... // program code
}
if (...)
{
... // program code
}
void ExampleFunction( void )
{
... // program code
}
【条款1-3-4 】相对独立的程序块之间必须加空行
CMonitorInfo objMonitorInfo;
GetMonitorInfo(&objMonitorInfo);
ShowMoitorInfo(&objMonitorInfo)
//注意此处要空行
CDiskInfo obDiskInfo;
GetDiskInfo(&obDiskInfo);
ShowDiskInfo(&obDiskInfo);
第四节 子程序的布局
【条款1-4-1 】一个函数体的代码行数应该推荐限制在80行内。
【条款1-4-2 】如果函数头太长需要分行,那么每个参数单独占一行。
示例:如下例子不符合规范:
BOOL OnPacketIoManagerEventHandle(PACKET_IO_MANAGER_EVENT nEvent, SEVERITY_LEVEL nSeverity, LPCTSTR lpTips)
应如下书写:
BOOL OnPacketIoManagerEventHandle(
PACKET_IO_MANAGER_EVENT nEvent
,SEVERITY_LEVEL nSeverity
,LPCTSTR lpTips
)
【条款1-4-3 】函数或过程的开始、结构的定义及循环、判断等语句中的代码都要采用缩进风格,case语句下的情况处理语句也要遵从语句缩进要求。
第五节 类的布局
【条款1-5-1 】类接口的布局
在布局类接口时,一般应将类成员按如下的顺序排列:
说明类及其完整用法的头部注释。
构造函数与析构函数
Public 子程序
Protected 子程序
Private子程序
【条款1-5-2 】类实现的布局
类实现通常应按如下的顺序排列:
概述类所在文件之内容的头部注释。
类数据
Public 子程序
Protected 子程序
Private子程序
第六节 文件布局
通常一个文件应只有一个类;文件名称应与类名有关;在文件中清晰的分隔各子程序
【条款1-6-1 】类实现的布局
C++源文件内容的典型顺序是:
文件的描述性注释
#include文件行
在多个类里使用的常量定义(如果文件里有多个类)
在多类里面使用的枚举(如果文件里有多个类)
宏函数定义
在多个类里使用的类型定义(如果文件里有多个类)
导入的全局变量和函数
导出的全局变量和函数
本文件使用的私用的变量和函数
各个类,包括各个类中的常量定义,枚举以及类型定义
第二章 注释
第一节 基本规则
【条款2-1-1 】最佳的注释量,约每十行语句有一个注释。
说明:注释的原则是有助于对程序的阅读理解,注释语言必须准确、易懂、简洁。
【条款2-2-2 】避免在注释中使用缩写,特别是非常用缩写。
说明:在使用缩写时或之前,应对缩写进行必要的说明。
【条款2-2-3 】注释的内容要清楚、明了,含义准确,防止注释二义性。
说明:错误的注释不但无益反而有害。
【条款2-2-4 】边写代码边注释,修改代码同时修改相应的注释,以保证注释与代码的一致性。不再有用的注释要删除。
【条款2-2-5 】注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。
示例:如下例子不符合规范。
例1:
// get replicate sub system index and net indicator
repssn_ind = ssn_data[index].repssn_index;
repssn_ni = ssn_data[index].ni;
例2:
repssn_ind = ssn_data[index].repssn_index;
repssn_ni = ssn_data[index].ni;
// get replicate sub system index and net indicator
应如下书写
// get replicate sub system index and net indicator
repssn_ind = ssn_data[index].repssn_index;
repssn_ni = ssn_data[index].ni;
【条款2-2-6 】对于所有有物理含义的变量、常量,如果其命名不是充分自注释的,在声明时都必须加以注释,说明其物理含义。变量、常量、宏的注释应放在其右方。
示例:
#define ACT_TASK_NUMBER_MAX 1000 ///< active statistic task number
【条款2-2-7 】数据结构声明(包括数组、结构、类、枚举等),如果其命名不是充分自注释的,必须加以注释。对数据结构的注释应放在其上方相邻位置,不可放在下面;对结构中的每个域的注释放在此域的右方。
示例:可按如下形式说明枚举/数据/联合结构。
/// @brief sccp interface with sccp user primitive message name
enum SCCP_USER_PRIMITIVE
{
SNP_UNITDATA_IND, ///< sccp notify sccp user unit data come
SNP_NOTICE_IND, ///< sccp notify user the No.7 network can not \n transmission this message
SNP_UNITDATA_REQ, ///< sccp user's unit data transmission request
};
【条款2-2-8 】全局变量要有较详细的注释,包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明。
示例:
// The ErrorCode when SCCP translate
// Global Title failure, as follows // 变量作用、含义
// 0 - SUCCESS 1 - GT Table error
// 2 - GT error Others - no use // 变量取值范围
// only function SCCPTranslate() in
// this modual can modify it, and other
// module can visit it through call
// the function GetGTTransErrorCode() // 使用方法
BYTE g_nGTTranErrorCode;
【条款2-2-9 】将注释与其上面的代码用空行隔开。
示例:如下例子,显得代码过于紧凑。
// code one comments
program code one
// code two comments
program code two
应如下书写
// code one comments
program code one
// code two comments
program code two
【条款2-2-10 】注释与所描述内容进行同样的缩排。
说明:可使程序排版整齐,并方便注释的阅读与理解。
示例:如下例子,排版不整齐,阅读稍感不方便。
void ExampleFunction( void )
{
// code one comments
CodeBlock One
// code two comments
CodeBlock Two
}
应改为如下布局。
void ExampleFunction( void )
{
// code one comments
CodeBlock One
// code two comments
CodeBlock Two
}
【条款2-2-11 】分支语句(条件分支、循环语句等)必须编写注释。
说明:这些语句往往是程序实现某一特定功能的关键,对于维护人员来说,良好的注释帮助更好的理解程序,有时甚至优于看设计文档。
分支语句例子:
// 如果加载驱动失败或者返回错误0x80070420(0x80070420错误是驱动已经加载)
// 就立即返回
if(0x80070420 != hr && FAILED(hr))
{
m_strErrMsg.Format(_T("Faile to start the '%s' minifilter driver (error code = %x)")
,FILE_FILEENCRYPTION_DRIVER,hr);
ATLTRACE(_T("%s\r\n"),m_strErrMsg);
return FALSE;
}
循环语句例子:
//扫描被打开文件的数组
STRING_ARRAY_ITR itr = m_arrOpenedFiles.begin();
for (; itr != m_arrOpenedFiles.end(); itr++)
{
//查找指定的文件,如果发现就立即返回
if ((*itr).Find(lpFileName))
{
refFilepath = (*itr);
bResult = TRUE;
break;
}
}
【条款2-2-12 】对于switch语句下的case语句,如果因为特殊情况需要处理完一个case后进入下一个case处理,必须在该case语句处理完、下一个case语句前加上明确的注释。
说明:这样比较清楚程序编写者的意图,有效防止无故遗漏break语句。
示例(注意斜体加粗部分):
switch(ch)
{
case CMD_FWD:
{
ProcessFwd();
if (...)
{
...
break;
}
else
{
ProcessCFW_B(); // now jump into case CMD_A
}
}
case CMD_A:
ProcessA();
break;
default:
}
【条款2-2-13 】switch语句的每一个分支需要有注释,放在右边。
例子:
// 根据不同的规则分配不同的缓冲区大小
switch (type)
{
case EFT_EXT_FILTER: //文件扩张名称过滤器
mem_size = sizeof(encrypt_file_filters_data_buffer) + sizeof(ext_filter_t) * filters;
break;
case EFT_PROCESS_FILTER: //进程过滤器
assert(EFT_PROCESS_FILTER == type);
mem_size = sizeof(encrypt_file_filters_data_buffer) + sizeof(process_filter_t) * filters;
break;
case EFT_DIR_FILTER: //目录过滤器
assert(EFT_DIR_FILTER == type);
mem_size = sizeof(encrypt_file_filters_data_buffer) + sizeof(dir_filter_t) * filters;
break;
default:
assert(0);
}
【条款2-2-14 】避免在一行代码或表达式的中间插入注释。
说明:除非必要,不应在代码或表达中间插入注释,否则容易使代码可理解性变差。
【条款2-2-15 】在代码的功能、意图层次上进行注释,提供有用、额外的信息。
说明:注释的目的是解释代码的目的、功能和采用的方法,提供代码以外的信息,帮助读者理解代码,防止没必要的重复注释信息。
示例:如下注释意义不大。
// if receive_flag is TRUE
if (receive_flag)
而如下的注释则给出了额外有用的信息。
// if mtp receive a message from links
if (receive_flag)
【条款2-2-16 】注释格式尽量统一,建议使用“//”。
【条款2-2-17 】注释应考虑程序易读及外观排版的因素,使用的语言若是中、英兼有的,建议多使用中文,除非能用非常流利准确的英文表达。
说明:注释语言不统一,影响程序易读性和外观排版,出于对维护人员的考虑,建议使用中文。
【条款2-2-18 】如果出现超长的程序块, 无法一屏显示,请在在程序块的结束行右方加注释标记,以表明某程序块的结束。
说明:当代码段较长,特别是多重嵌套时,这样做可以使代码更清晰,更便于阅读。
示例:参见如下例子。
if (...)
{
// program code
while (index < MAX_INDEX)
{
// program code
} // end of while (index < MAX_INDEX) 指明该条while语句结束
} // end of if (...) // 指明是哪条if语句结束
第二节 注释方法
【条款2-2-1 】文件头(包含头文件.h和实现文件.c,.cpp)必须注释,其它文件若有必要也要注释,注释内容包含文件名称、简要说明、详细说明(可选)、作者、版本号、日期等,参见下面的格式。
/
/// COPYRIGHT NOTIC
/// Copy right (c) ${year}, Ax3soft Co., Ltd.
/// All rights reserved.
///
/// @file $URL$
/// @brief
///
///
// $Id$
// $LastChangedDate$
// $LastChangedRevision$
// $LastChangedBy$
/
【条款2-2-2 】命名空间也需要注释,包含简要说明和详细说明(可选),参见下面的格式:
/// @brief 简要说明
///
/// 详细说明至少两行,并且与简要说明之间留一行空格
Namespace test
{
}
【条款2-2-3 】类的定义也需要注释,包含简要说明和详细说明(可选),参见下面的格式:
//*******************************************************************
/// @brief 简要说明
///
/// 详细说明至少两行,并且与简要说明之间留一行空格
//*******************************************************************
Class CTest
{
public:
UINT m_nMode; ///< 测试方法
}
【条款2-2-3 】结构定义也需要注释,包含简要说明和详细说明(可选),参见下面的格式:
/// @brief 数据包头
///
/// 专用的数据包头,用于可靠的数据通信
typedef struct _sax2_packet_header
{
U32 nMagic; ///< 包头识别码'0xFFFEFDFC'
U32 nID; ///< 消息ID
U8 nVersion; ///< 版本号,当前是1
U8 nFlags; ///< 标志, 前4位表示版本,紧接着4位是
U32 nChecksum; ///< 校验和,采用与TCP相同计算方法,需要计算的数据包括包头和载荷数据
U32 nPayloadLen; ///< 携带的数据长度
U16 nPaddingLen; ///< 填充数据长度的长度
}SAX2_PACKET_HEADER;
【条款2-2-4 】枚举常量定义也需要注释,包含简要说明和详细说明(可选),参见下面的格式:
/// 服务器状态枚举定义
///
/// 该枚举定义了服务器事务对象可能处于的状态类型\n
enum NET_TRANSACTION_STATUS
{
SS_INVALID = 0, ///< 枚举,无效状态
SS_INITIALIZED, ///< 枚举,已经成功初始化
SS_RUNING, ///< 枚举,正在运行状态
SS_STOP, ///< 枚举,停止状态
};
【条款2-2-5 】函数头部应进行注释,列出:函数的目的/功能、输入参数、输出参数、返回值、使用注意,作者等信息。
- 若是在头文件的声明处,使用 brief
/// @brief Abrief function description
- 在现实文件或者是在头文件处,声明和定义重合,使用 brief + detailed
//----------------------------------------------------------------
// @routine
/// @brief A brief function description.
///
/// A detailed description, it
/// should be 2 lines at least.
/// @param 可带描述选项【_in |_out |_inout】
/// @return 返回值说明
/// @note (可选项@warning @see )
/// @author
//---------------------------------------------------------------
【条款2-2-6 】类成员变量、结构成员、枚举常量成员、全局常量或变量,都在其右边使用 "///<"进行注释,全局变量还要遵守条款2-2-8
全局常量例子:
const DWORD TIME_SCAN_WORKING = 1000 *