C++编码规范.docx

C+编码规范C+编码规范Version: 1.0.1DocCode: Date: 2013-5-29重要声明版权声明本文档中的任何内容受中华人民共和国著作权法的保护，版权所有 2015, 展讯通信有限公司，保留所有权利，但注明引用其他方的内容除外。商标声明展讯通信有限公司和展讯通信有限公司的产品是展讯通信有限公司专有。在提及其他公司及其产品时将使用各自公司所拥有的商标，这种使用的目的仅限于引用。不作保证声明展讯通信有限公司不对此文档中的任何内容作任何明示或暗示的陈述或保证，而且不对特定目的的适销性及适用性或者任何间接、特殊或连带的损失承担任何责任。保密声明本文档（包括任何附件）包含的信息是保密信息。接收人了解其获得的本文档是保密的，除用于规定的目的外不得用于任何目的，也不得将本文档泄露给任何第三方。目 录目 录3一、简介4二、程序版式52.1空行52.2代码行62.3修饰符的位置82.4代码行内的空格92.5对齐102.6注释122.7类的版式14三、命名规则163.1共性规则163.2宏183.3标识符18四、函数规范194.1参数规则194.2返回值规则204.3函数体20五、界面规范215.1对话框215.2控件225.3主命令按钮235.4规范性25六、公用库26七、其它277.1语言277.2通用规则277.3通用规范287.4类的范例30八、团队合作32附录A：Revision History33一、 简介该文档列举了一些基本的编程技能并提供了一些好的编程习惯。其主要作用是增强程序的可读性和可维护性。保证一个开发小组产生高质量的代码的最容易的方式就是建立一个编程规范，并通过日常的代码检视保证其被严格遵守。一个全面的编程规范应该覆盖构成代码的所有部分，这样所有开发者就可以在他的实现中严格遵守。所有的代码就会具有一致的风格，如同出自一个开发者之手。虽然代码检视的主要作用是在整个开发生命周期中来发现代码中存在的缺陷，但其也可以用来保证编程规范的贯彻。说明：该文档中类似于“【规则5.1.1】”加灰显示的章节，为编程建议，不做强制要求。二、 程序版式122.1 空行【规则2.1.1】在每个类声明之后、每个函数定义结束之后都要加空行。【规则2.1.2】在一个函数体内，逻辑上密切相关的语句之间不加空行，其它地方应加空行分隔。【规则2.1.3】加空行时，一般不同时出现两个连续空行。函数之间的空行函数内部的空行/ 空行void Function1()/ 空行void Function2()/ 空行void Function3() / 空行while (condition)statement1;/ 空行if (condition)statement2;elsestatement3;/ 空行statement4;dosomething();/ 空行return true;2.2 代码行【规则2.2.1】 一行代码只做一件事情，如只定义一个变量，或只写一条语句。这样的代码容易阅读，并且方便于写注释。【规则2.2.2】 if、for、while、do等语句自占一行，执行语句不得紧跟其后。不论执行语句有多少都要加。这样可以防止书写失误。良好的风格不良的风格int width; / 宽度int height; / 高度int depth; / 深度int width, height, depth; / 宽度高度深度x = a + b;y = c + d;z = e + f;X a + b; y = c + d; z = e + f;if (width height) dosomething();if (width other_thing &third_thing = fourth_thing &yet_another != last_one) .2.4 代码行内的空格【规则2.4.1】关键字之后要留空格。象const、virtual、inline、case 等关键字之后至少要留一个空格，否则无法辨析关键字。象if、for、while等关键字之后应留一个空格再跟左括号（，以突出关键字。【规则2.4.2】 函数名之后不要留空格，紧跟左括号（，以与关键字区别。【规则2.4.3】 （向后紧跟，）、，、;向前紧跟，紧跟处不留空格。【规则2.4.4】 ，之后要留空格，如Function(x, y, z)。如果;不是一行的结束符号，其后要留空格，如for (initialization; condition; update)。【规则2.4.5】 赋值操作符、比较操作符、算术操作符、逻辑操作符、位域操作符，如“=”、“+=” “=”、“=”、“+”、“*”、“%”、“&”、“|”、“”这类操作符前后不加空格。良好的风格不良的风格Void Func1(int x, int y, int z);void Func1 (int x,int y,int z);if (year = 2000)if(year=2000)if (a = b) & (c =b&c=d)for (i=0; i10; i+)for(i=0;i10;i+)x = a b ? a : b;x=aFunction();不要写成 b - Function();2.5 对齐【规则2.5.1】 缩进用 TAB，不用空格，设置一个 TAB 缩进4个空格，以此对齐代码。【规则2.5.2】 注释与代码对齐。良好的风格不良的风格for (initialization; condition; update) / 注释 dosomething();for (initialization; condition; update)/ 注释 dosomething();【规则2.5.3】 程序的分界符和应独占一行并且位于同一列，同时与引用它们的语句左对齐。良好的风格不良的风格for (initialization; condition; update) / program codefor (initialization; condition; update) / program code 【规则2.5.4】 之内的代码块在右边数格处左对齐。良好的风格不良的风格void Function(int x) / program codevoid Function(int x) / program codeif (condition) / program codeelse / program codeif (condition) / program codeelse / program codefor (initialization; condition; update) / program codefor (initialization; condition; update) / program codeWhile (condition) / program codewhile (condition) / program code如果出现嵌套的，则使用缩进对齐，如： 2.6 注释【规则2.6.1】 保持注释和代码的同步，当修改代码后，同时修改相应的注释，以保证注释与代码的一致性，无用的注释要删除掉。【规则2.6.2】 注释的位置应与被描述的代码相邻，可以放在代码的上方或右方，不可放在下方。【规则2.6.3】 注释采用“/”，避免使用“/*/”来注释，对大段的注释也是如此，但对于函数定义中默认值的注释例外。【规则2.6.4】 中文注释采用中文标点符号。【规则2.6.5】 在注释符“/”后留一个空格，再开始注释的内容。【规则2.6.6】 多个变量、枚举注释时，将注释使用TAB（用编辑器将TAB设为4个空格）对齐，使代码美观整齐。良好的风格不好的风格int width = 10; / 定义并初绐化widthint width= 10; / 定义并初始化 widthTCHAR szBuf10 =0; / 定义并初绐化int height = 10; / 定义并初绐化heightTCHAR szBuf10 = 0; /*定义并初始化*/int height = 10; /定义并初绐化height【规则2.6.7】不要吝啬注释，在任何不是其他人很容易读懂的地方加注释。公司公用库的类和函数必须有注释（私有函数可以不注释）；接口类的接口函数，必须有注释；复杂算法的函数，必须有注释。【规则2.6.8】 每个函数和类的注释以/ -（120个“-”）开始和结束。【规则2.6.9】 注释内容需要换行时，与上一行的注释内容对齐。【规则2.6.10】 参数说明以“-”字符对齐，可以在参数名称右侧补充空格或TAB。【规则1.6.11】 枚举值的注释可以直接在其后说明，但注释必须对齐。【规则1.6.12】 注释内容一行最长不超过60个汉字（即“/ ”后面的内容），超过60个汉字需要换行，换行后的注释内容与上一行的内容保持对齐。【规则2.6.13】函数注释范例。（为阅读方便对“-”做了一些删减）：/ -/ Summary: / 设置指定字段的值，可以根据字段名称或者字段序号/ Parameters:/ nIndex - 字段序号/ lpFieldName - 字段名称/ lValue - 整形数据值/ lValue - 长整形数据值/ lValue - 无符号长整形数据值/ dblValue - 双精度浮点数据/ strValue - 字符串/ time - 时间类型/ bValue - bool类型/ cyValue - 货币类型/ vtValue - 变体类型/ Returns:/ 设置成功返回TRUE，否则返回FALSE。/ Example:/ 添加一条新记录。/ / CADORecordset* prs = new CADORecordset(m_pAdoDb);/ prs-Open(Test, openTable);/ / prs-AddNew();/ prs-SetFieldValue(0, dataU);/ prs-SetFieldValue(1, data01);/ prs-SetFieldValue(2, (long)51000);/ COleDateTime time = COleDateTime(2001,6,15, 10, 8, 30);/ prs-SetFieldValue(3, time);/ prs-Update();/ prs-Close();/ delete prs;/ / -BOOL SetFieldValue(LPCTSTR lpFieldName, _variant_t vtValue);【规则2.6.13】文件注释范例。首行和末行顶格开始，共计80个字符；中间所有行前空两个空格。所有“:”上下对齐。/* Copyright (c), 2002 - 2012, SpreadTrum Tech. Co., Lid. * FILE Name : DisableWarningMacro.h Version : 1.0.001 Author : Penghui.Yin Created : 2012/12 Last Modified : Description : This file defines the Macro to disable warning such as strcpys、strcat_s、_vswprintf etc. Function List : History : Date : 2012/12 Author : Modification : Created file*/2.7 类的版式【规则2.7.1】 将public类型的函数(与成员变量)写在前面，而将private类型的函数(与成员变量)写在最后面，protected类型的(与成员变量)位于两者中间。将成员函数与成员函数放在一起，成员变量与成员变量放一起，消息处理函数与消息处理函数放一起。良好的风格不好的风格class Apublic: void Func1(void); void Func2(void);protected:virtual void OnOK(); virtual BOOL OnInitDialog(); afx_msg void OnPaint(); afx_msg HCURSOR OnQueryDragIcon(); DECLARE_MESSAGE_MAP() HICON m_hIcon;private: int m_nCount; int m_nIndex; float m_fX; float m_fY;class Aprivate: int i, j; float x, y;protected:virtual void OnOK(); virtual BOOL OnInitDialog(); afx_msg void OnPaint(); afx_msg HCURSOR OnQueryDragIcon(); DECLARE_MESSAGE_MAP() HICON m_hIcon;public: void Func1(void); void Func2(void);【规则2.7.2】构造函数初始化列表放在同一行或顶格并排几行。良好的风格不好的风格A:A(int var1, int var2) : _var1(var1), _var2(var2)A:A(int var1, int var2, int var3, int var4): m_var1(var1), m_var2(var2), m_var3(var3), m_var4(var4).DoSomething();.A:A(int var1, int var2, int var3, int var4): m_var1(var1), m_var2(var2), m_var3(var3), m_var4(var4).DoSomething();.【规则2.7.2】成员函数用名称区分是否属于Public类型。例如：良好的风格不好的风格class Apublic: void Func1(void); void Func2(void);protected: void _func3(void);private:void _func4(void);class Apublic: void Func1(void); void Func2(void);protected: void Func3(void);private:void Func4(void);三、 命名规则33.1 共性规则【规则3.1.1】 标识符最好采用英文单词或其组合，便于记忆和阅读。尽量不使用汉语拼音来命名。程序中的英文单词一般不会太复杂，用词应当准确。除标准缩写单词外，不建议采用缩写方式，而应该采用全名，并且让人一看就明白代表的含义。【规则3.1.2】 标识符的长度应当符合“min-length & max-information”原则。标识符名称可以使用长名称，但也不宜过长，能表达清楚信息即可。【规则3.1.3】 标识符命名规则与MFC的风格保持一致，采用“大小写”混排的方式。良好的风格不好的风格AddChildadd_child【规则3.1.4】 程序中不要出现仅靠大小写区分的相似的标识符。例如：int x, X; / 变量x 与 X 容易混淆void foo(int x); / 函数foo 与FOO容易混淆void FOO(float x);【规则3.1.5】 避免使用单个字母的变量如i, n, x，使用 index, temp等，但用于循环迭代的变量例外。例如：for (int i = 0; i owner = THIS_MODULE; while (0)3.3 标识符【规则3.3.1】 标识符命名遵循“匈牙利”命名规则。常用标识符前缀如下：类型前缀示例charchchar ch;bool、BOOLb、isBOOL bPass;bool isPass;int、longnint nMinValue;float、doubleddouble dRate;指针pBYTE* pBuffer;CStringstrCString strName;CStringArraystrArrCStringArray strArrName;DWORDdwDWORD dwParam;HANDLEhHANDLE hWnd;按钮btnCButton m_btnSelectEnt;编辑框editCEdit m_editName;组合框cboCComboBox m_cboAge;列表框lstCListBox m_lstAge;列表控件lct、wndCListCtrl m_lctGrid;CListCtrl m_wndGrid;四、 函数规范44.1 参数规则【规则4.1.1】 如果参数是指针，且仅作输入用，则应在类型前加const，以防止该指针在函数体内被意外修改。例如：void StringCopy(char* strDestination，const char* strSource);【规则4.1.2】 如果输入参数以值传递的方式传递对象，则宜改用“const&”方式来传递，这样可以省去临时对象的构造和析构过程，提高效率。【规则4.1.3】 对于重载的虚函数，在派生类的函数声明前加入“virtual”关键字。良好的风格不好的风格class Apublic:virtual void Func1(void);class B : public Apublic:virtual void Func1(void);class Apublic: virtual void Func1(void);class B : public Apublic:void Func1(void);【规则4.1.4】尽量放在同一行，否则，将实参封装在圆括号中。【规则4.1.5】如果同一行放不下，可断为多行，后面每一行都和第一个实参对齐，左圆括号后和右圆括号前不留空格：例如：bool retval = DoSomething(averyveryveryverylongargument1,argument2, argument3);【规则4.1.6】如果函数参数比较多，可以出于可读性的考虑每行只放一个参数：例如：bool retval = DoSomething(argument1,argument2,argument3,argument4);【规则4.1.7】如果函数名太长，以至于超过行最大长度，可以将所有参数独立成行：例如：DoSomethingThatRequiresALongFunctionName(very_long_argument1,argument2,argument3,argument4);4.2 返回值规则【规则4.2.1】 不省略返回值的类型。如果函数没有返回值，则应声明为void类型。【规则4.2.2】 从不返回函数体内局部变量的指针或引用。【规则4.2.3】 在函数体的“入口处”，使用断言对参数的有效性进行检查。例如：void* Memcpy(void *pvTo, const void *pvFrom, size_t size)assert(pvTo != NULL) & (pvFrom != NULL);/ 使用断言byte* pbTo = (byte*)pvTo; / 防止改变pvTo的地址byte* pbFrom = (byte*)pvFrom; / 防止改变pvFrom的地址while(size- 0)*pbTo+ = *pbFrom+;return pvTo;4.3 函数体【规则4.3.1】推荐函数的圈复杂度不应超过9。圈复杂度指示一个函数可执行路径的数目，以下语句为圈复杂度的值贡献1：if/else/for/while语句，三元运算符语句，if/for/while判断条件中的“&”或“|”，switch语句，后接break/goto/ return/throw/continue语句的case语句，catch/except语句；推荐值为69;【规则4.3.2】需要明确规定对接口函数的参数的合法性检查，是由函数调用方还是接口函数本身负责，一般是由接口函数本身负责。【规则4.3.3】设计高扇入，合理扇出（小于7）的函数。说明：扇入指有多少上级函数调用它，扇出是它直接调用的函数数目。五、 界面规范55.1 对话框【规则5.1.1】 对话框字体采用“宋体”，字号为小五号字（9磅）。【规则5.1.2】 带文字的按钮采用50个对话框单位（75个像素点）的最小宽度、14个对话框单位（21个像素点）的标准高度。【规则5.1.3】 如果“帮助”按钮没有真正的功能，那就不要提供“帮助”按钮，除非链接到相关的帮助文件或提供真正有用的附加信息。【规则5.1.4】 尽可能提供快捷键。特别对于常用按钮和有大量录入项的界面，能让用户不使用鼠标即可完成快速数据录入。例外的情况是：“确定”按钮可以没有快捷键，因为在作为默认按钮时，Enter 键就是它的快捷键。“取消”按钮也可以没有快捷键，因为 ESC 键是它的快捷键。【规则5.1.5】 对话框中控件的TAB按键激活顺序应该与控件排列顺序一致，即遵循从上到下、从左到右这样一个流程。【规则5.1.6】 空格的使用。使用空格可以使窗口布局更易于理解，并且查看起来更舒服。空格的多少要适当，不要显得太分散。但要避免过多地使用空格。如果可能，尽量使窗口小一些。【规则5.1.7】 对话框中用户输入数据后不要立即验证数据并马上提示用户数据无效，应该在用户单击“确定”或等效按钮时验证数据，如果需要立即验证数据，最好不要采用弹出消息框的方式来提示用户。5.2 控件【规则5.2.1】所有控件使用大小统一的字体属性，除了特殊提示信息、加强显示等例外情况。【规则5.2.2】完成相同或相近功能的控件用Frame框起来，放在集中位置，减少鼠标移动的距离。【规则5.2.3】 控件的标签文本应使用半角符号，指导性标签文本（如解释按钮功能的句子），则使用全角符号，并且句子应遵循中文标点符号标准。【规则5.2.4】 将不适用于当前程序状态的控件置为不可用（变灰），一般情况下不要隐藏控件，也要避免使控件可用但单击后产生一条出错信息。【规则5.2.5】 在控件文本后附加省略号“.”来表示需要更多信息，省略号表示执行时需要更多信息，而不是简单的确认。单击带有省略号的控件后一般都会出现对话框，但也可能是别的控件。【规则5.2.6】 选项数较少时使用选项框，选项数较多或界面空间较小时使用下拉列表框。【规则5.2.7】 适当使用只读编辑框（如非标签文本），只读编辑框允许用户将文本复制到剪贴板上，并在文本比控件长时可进行滚动。【规则5.2.8】 避免出现水平滚动条，水平滚动条会使项目阅读起来比较困难。可以通过加宽窗口或使文本自动换行等方法避免。当然，如果确实需要，还是可以使用水平滚动条。【规则5.2.9】 通常使用左对齐来使用户界面控件更易于浏览。对于数值文本，应该使用小数点对齐或右对齐。对于非数值文本，应该避免使用右对齐或居中对齐。有时在右边或底部保留空白区域可能更适合习惯。5.3 主命令按钮【规则5.3.1】 对于模态对话框，通常提供“确定”和“取消”两个主命令按钮。可以使用更明确的按钮代替“确定”按钮，但绝对不要在模态对话框中替换“取消”按钮，除非用“停止”来表明正在进行的操作无法取消。【规则5.3.2】 对于非模态对话框或作为主窗口的对话框，提供“关闭”主命令按钮而不提供“确定”和“取消”按钮。因为在非模态对话框里，“确定”和“取消”是没有什么意义的，使用“关闭”按钮可以消除这种混淆，而且这样可以更明确的区分模态对话框和非模态对话框。【规则5.3.3】 主命令按钮的文字一般为“确定”、“取消”、“帮助”，避免界面中出现相同功能但按钮文字不一致的情况，如“退出”、“关闭”等。【规则5.3.4】 将主命令按钮与对话框主体分开，以便使主命令按钮更易于查找和识别。【规则5.3.5】 主命令按钮的位置一般位于对话框底部或右侧的位置。【规则5.3.6】 当主命令按钮位于对话框底部时，应该右对齐主命令按钮。但当只有一个主命令按钮时，可以将其居中放置。【规则5.3.7】 主命令按钮的顺序通常为“确定”第一，“取消”其次，“帮助”最后。如果没有确定按钮，应该将“取消”按钮放在“帮助”按钮的前面。【规则5.3.8】 对话框的默认按钮为“确定”或等价按钮。不好的风格（只有确定按钮，用户无法取消操作）：不好的风格（确定、取消没有右对齐且大小不一致）：5.4 规范性【规则5.4.1】 菜单深度一般要求最多控制在三层以内。【规则5.4.2】 程序主界面的图标为软件图标，标题为产品名称。【规则5.4.3】 公司名称及产品名称应只在“关于对话框”中出现，不要到处显示公司名称或产品的名称。【规则5.4.4】 帮助菜单的“关于”中应有版权和产品信息。推荐使用XAbout的帮助。【规则5.4.5】 系列产品要保持一致的界面风格，如背景色、字体、菜单排列方式、图标、安装过程、按钮用语等应该大体一致。【规则5.4.6】 不同界面中的同一功能应该使用同样的图标和图片。图标、图片的色调、风格尽量保持一致。图标、图片的隐喻应能确切表示功能的含义，如果不能，就直接使用文本，以免混淆用户。如果功能是一个动作时，可能比较难找到确切表示该功能的图标，这时应该尽量采用此动作相关的名词做图标。例如Windows中的“剪切”功能就是用一把剪刀来表示的。六、 公用库公用库入库需要满足以下几个条件：1. 与公用库中现有功能不重复，开发人员或软件中需要的功能。2. 提供功能说明文档及概要设计文档，最好有一份较为详细的教程。3. 符合公司软件的编码规范、界面规范，以及公用库的注释要求。4. 有完善的帮助文档，所有public、protected类型的函数、枚举等均应有注释。5. 提供示例程序，演示到类或函数的大多数或常用功能。6. 对于算法公用库，应有采用CppUnit做单元测试的代码。7. 在加入公用库后对所有开发人员做一次讲解（针对比较大的库）。8. 应该经过至少一个软件的实际使用。9. 应能分别在Release、Debug配置下编译通过，并保证两个版本的功能均能正确使用。10. 考虑到兼容性，要同时支持VC6、VC9两个平台，并在UNICODE编码下通过编译。11. 在后期发现BUG或需要扩充功能时，能提供一定的时间来维护。七、 其它677.1 语言【规则7.1.1】 布尔类型采用宏定义的BOOL类型。7.2 通用规则【规则7.2.1】全局变量class 类型的全局变量是被禁止的，包括STL 的string, vector 等等。对于全局的字符串常量，使用C 风格的字符串，而不要使用STL 的字符串：const char kFrogSays = ribbet;内建类型的全局变量是允许的，当然多线程代码中非常数全局变量也是被禁止的。永远不要使用函数返回值初始化全局变量。如果一定要使用class类型的全局变量，请使用单件模式(singleton pattern)原因： 全局变量的构造函数、析构函数以及初始化操作的调用顺序只是被部分规定，每次生成有可能会有变化，从而导致难以发现的bugs。 包括STL 的string, vector 等等，因为它们的初始化顺序有可能导致构造出现问题【规则7.2.2】memset禁止对结构体使用memset。若万不得已要使用，必须保证结构体的全部成员都是内建类型。结构体的初始操作一般在构造函数内完成。【规则7.2.3】在条件表达式中使用左值判断在条件表达式中使用左值判断，可以将因手误少写一个“=”号带来的问题在编译阶段被发现，例如：良好的风格不好的风格if (NULL = p)if (p = NULL)if (100 = nNum)if (nNum = 100)if (mapVar.end() = it) if (it = mapVar.end() 【规则7.2.3】禁用三目运算符禁用三目运算符可以防止运算符优先级关系而导致的难以发现的Bug。【规则7.2.4】禁止将布尔变量直接与TRUE、FALSE或者1、0进行比较。良好的风格不好的风格if (flag) / 表示flag为真 .if (!flag) / 表示flag为假 .if (flag = TRUE) .if (flag = 1 ) .if (flag = FALSE) .if (flag = 0) .【规则7.2.5】禁止在ASSERT中使用影响程序逻辑的表达式。例如：ASSERT(100 = +nIndex);这样的代码应该避免，因为表达式中改变了nIndex的值，影响了程序的逻辑，在Debug版和Release中会有不同的结果。7.3 通用规范【规则7.3.1】 清楚一致的设计。所有界面的风格保持一致，所有具有相同含义的术语保持一致，且易于理解。【规则7.3.2】 在长时间操作时，要确保有等待光标、进度条或其它可视的反馈。如有可能，应提供取消长时间操作的功能。如果可以取消未完成的操作，应