软件开发代码规范(C语言)

1、 XX产品研究部文 档 编 号产品版本密级开发适用共 页收文：XX产品研究部软件开发人员 软件开发代码规范(仅供内部使用)拟制：周超日期：2011-5-11审核：日期：核准：日期：签发：日期：文档版本：V0.11目录第一章 原则5第二章 排版62.1空行62.2代码行72.3代码行内的空格72.4对齐缩进82.5长行拆分9第三章 注释113.1通用规则113.2文件注释113.3函数注释123.4数据注释133.5代码注释13第四章 命名164.1通用命名规则164.2文件命名164.3类型命名164.4变量命名174.5常量命名184.6函数命名184.7枚举命名184.8宏命名18第五章

2、杂项20文件修改记录修改日期版本修改页码、章节、条款修改描述作者2011-4-290.1创建初稿周超2011-5-110.113.3数据注释4.3类型命名4.4变量命名4.6函数命名1）修改3.4数据注释【规则3-4-3】全局变量注释例子2）在“4.3类型命名”、“4.4变量命名”、“4.6函数命名”中，增加对前缀、关键缩写词等可以适当全部大写的处理。周超第一章 原则本文档的目的是提供一个公共的编码规范。这个规范详细阐述在编码时要怎样写、不要怎样写，旨在提高代码的可读性、可维护性，使代码易于管理，使所有人可以集中精力去实现内容，而非处理各种复杂的表现形式。使代码易于管理的方法之一是增强代码一致

3、性，让别人可以读懂你的代码是很重要的，保持统一编程风格意味着可以轻松根据“模式匹配”规则推断各种符号的含义。创建通用的、必需的习惯用语和模式可以使代码更加容易理解。虽然在某些情况下改变一些编程风格可能会是好的选择，但我们还是应该遵循一致性原则，尽量不这样去做。关键在于保持一致。第二章 排版2.1 空行l 【规则2-1-1】在每个函数、结构体、枚举定义结束之后都要加空行。l 【规则2-1-2】在一个函数体内，逻辑密切相关的语句之间不加空行，其它地方应加空行分隔。struct st1 ;/ 空行enum ;/ 空行void Function1() / 空行void Function2() / 空行

4、while (condition)statement1;/ 空行if (condition) statement2;elsestatement3;/ 空行statement4; 函数之间的空行 函数内部的空行l 【规则2-1-3】相对独立的程序块之间、变量说明之后必须加空行。if (!is_lock_card_succ). / program codeGetLockPhoneInfo(&st_lock_phone_info);if (!is_lock_card_succ). / program code/空格GetLockPhoneInfo(&st_lock_phone_inf

5、o); 不规范代码 规范代码2.2 代码行l 【规则2-2-1】一行代码只做一件事情，如只定义一个变量，或只写一条语句。这样的代码容易阅读，并且方便于写注释。l 【规则2-2-2】if、for、while、do等语句自占一行，执行语句不得紧跟其后。不论执行语句有多少都要加。这样可以防止书写失误。int width, height, depth;/ 宽度高度深度int width; / 宽度int height;/ 高度int depth;/ 深度X a + b; y = c + d; z = e + f;x = a + b;y = c + d;z = e + f;if (width <

6、height) dosomething();if (width < height) dosomething();for (initialization; condition; update) dosomething();other();for (initialization; condition; update)dosomething();/ 空行other();不规范代码 规范代码2.3 代码行内的空格说明：空格的目的在于更清晰的代码。l 【规则2-3-1】关键字之后要留空格。const、static等关键字之后至少要留一个空格，否则无法辨析关键字；if、for、while、switc

7、h等关键字之后应留一个空格再跟左括号(，以突出关键字。l 【规则2-3-2】函数名之后不要留空格，紧跟左括号(，以与关键字区别。l 【规则2-3-3】(向后紧跟，)、,、;向前紧跟，紧跟处不留空格。l 【规则2-3-4】,之后要留空格，如Function(x, y, z)。如果;不是一行的结束符号，其后要留空格，如for (initialization; condition; update)。l 【规则2-3-5】赋值操作符、比较操作符、算术操作符、逻辑操作符、位域操作符，如“=”、“+=” “>=”、“<=”、“+”、“*”、“%”、“&&”、“|”、“<&

8、lt;”,“”等二元操作符的前后应当加一个空格。l 【规则2-3-6】一元操作符如“!”、“”、“+”、“-”、“&”（地址运算符）等前后不加空格。l 【规则2-3-7】象“”、“.”、“->”这类操作符前后不加空格。l 【建议2-3-1】对于表达式比较长的for语句和if语句，为了紧凑起见可以适当地去掉一些空格，如for (i=0; i<10; i+)和if (a<=b) && (c<=d)void Func1(int x, int y, int z);void Func1 (int x,int y,int z);if (year >=

9、2000)if(year>=2000)if (a>=b) && (c<=d)if (a >= b) && (c <= d)if(a>=b&&c<=d)for (i = 0; i < 10; i+)for (i=0; i<10; i+)for(i=0;i<10;i+)x = a < b ? a : b;x=a<b?a:b;i+;int *x = &y;i +;int * x = & y; array5 = 0;a.Function();b->Functio

10、n();array 5 = 0;a . Function();b -> Function();良好风格 不良风格2.4 对齐缩进l 【规则2-4-1】程序块要采用缩进风格编写。l 【规则2-4-2】对齐使用TAB键，TAB键宽度设置为4个空格。说明：应注意使用不同编辑器时，TAB键设置不同造成的排版不同；应注意某些编辑器在识别、显示TAB键上存在问题；最终排版应以在项目的主代码编辑器（如VC、Source Insight等）中显示一致统一、整洁清晰为准。Source Insight中设置：Options->Doucument Options->“Tab Width:4”l 【

11、规则2-4-3】函数或过程的开始、结构的定义及循环、判断等语句中的代码都要采用缩进风格，case语句下的情况处理语句也要遵从语句缩进要求。l 【规则2-4-4】程序块的分界符（如和）应各独占一行并且位于同一列，同时与引用它们的语句左对齐。在函数体的开始、类的定义、结构的定义、枚举的定义以及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。for (.) . / program codefor (.) . / program codeif (.) . / program code if (.) . / program codevoid example_fu

12、n( void ) . / program code void example_fun( void ) . / program code不规范代码 规范代码l 【规则2-4-5】预处理指令不需要缩进，总是从行首开始。即使预处理指令位于缩进代码块中，指令也应从行首开始。/ 良好风格：预处理指令均从行首开始 if (lopsided_score) #if DISASTER_PENDING / Correct - Starts at beginning of line DropEverything();#if NOTIFY NotifyClient();#endif#endif BackToNorm

13、al(); / 不良风格：缩进的预处理指令 if (lopsided_score) #if DISASTER_PENDING / Wrong! The "#if" should be at beginning of line DropEverything(); #endif / Wrong! Do not indent "#endif" BackToNormal(); 2.5 长行拆分l 【规则2-5-1】代码行最大长度宜控制在100至110个字符以内。代码行不要过长，否则眼睛看不过来，也不便于打印。l 【规则2-5-2】较长的语句（>110字符）

14、要分成多行书写；长表达式要在低优先级操作符处拆分成新行，操作符放在新行之首（以便突出操作符）。拆分出的新行要进行适当的缩进，使排版整齐，语句可读。l 【规则2-5-3】循环、判断等语句中若有较长的表达式或语句，则要进行适应的划分. 长表达式要在低优先级操作符处划分新行，操作符放在新行之首。l 【规则2-5-4】若函数或过程中的参数较长，则要进行适当的划分。if (very_longer_variable1 >= very_longer_variable12)&& (very_longer_variable3 <= very_longer_variable14)&am

15、p;& (very_longer_variable5 <= very_longer_variable16) dosomething();virtual CMatrix CMultiplyMatrix (CMatrix leftMatrix, CMatrix rightMatrix);for (very_longer_initialization; very_longer_condition; very_longer_update)dosomething();report_or_not_flag = (taskno < MAX_ACT_TASK_NUMBER) &&a

16、mp; (n7stat_stat_item_valid (stat_item) && (act_task_tabletaskno.result_data != 0);n7stat_str_compare(BYTE *) & stat_object, (BYTE *) & (act_task_tabletaskno.stat_object), sizeof (_STAT_OBJECT);长行的拆分第三章 注释3.1 通用规则l 【规则3-1-1】一般情况，需要保证程序有一定的注释。必须保证关键的函数、流程、类型定义、变量等有相应注释说明。说明：注释的原则是有助于对

17、程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、。l 【规则3-1-2】注释应当准确、易懂，防止注释有二义性。说明：错误的注释不但无益反而有害。l 【规则3-1-3】除非能使用准确的英文表达，则使用中文注释。l 【规则3-1-4】避免在注释中使用缩写，特别是非常用缩写。说明：在使用缩写时或之前，应对缩写进行必要的说明。l 【规则3-1-5】需要为代码中使用的缩写增加注释,文件引入的新缩写必须在文件头部加以说明。l 【规则3-1-6】通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构，使代码成为自注释的。说明：清晰准确的函数、变量等的命名，可增加

18、代码可读性，并减少不必要的注释。l 【规则3-1-7】注释格式尽量统一。建议使用/进行注释，多行注释可使用“/* */”。3.2 文件注释l 【规则3-2】源文件（包含.h头文件、.c源文件及各种脚本文件等）头部应进行注释，应列出：版权说明、文件名、文件目的/功能，作者、创建日期等；如果源文件引入了新的缩写，则必须在文件头部注释说明。文件注释格式定义如下（可以不局限于该格式中定义的内容，但必须包含该格式中定义的内容）：/* Copyright (C) 2010-2011, XXX Co. Ltd.* All rights reserved.* FileName: / 文件名称* Descrip

19、tion: / 文件描述* Author: / 作者* Date: / 创建时间* Others: / 其它说明*/* Abbreviation: / 如果文件引入了新的缩写，则必须在此处加以说明*/举例如下：/* Copyright (C) 2010-2011, XXX Co. Ltd.* All rights reserved.* FileName: starlib_nvset.h* Description: NV参数配置源文件* Author: zc* Date: 2010/4/13* Others: */*Abbreviation:NCM: Net Choose Menu 网络选择菜单

20、VBC: Voice Broadcast 语音播报 */3.3 函数注释l 【规则3-3】函数头部应进行注释，需要列出函数的功能、参数、返回值等。函数注释格式定义如下（可以不局限于该格式中定义的内容，但必须包含该格式中定义的内容）：/*/ Function: / 函数名称/ Description: / 函数功能描述/ Param: / 参数说明，包括参数的作用、取值范围等，格式如下：/ param1: 输入输出类型IN/OUT/INOUT 说明/ param2: 输入输出类型IN/OUT/INOUT 说明/ / Return: / 函数返回值说明/ Others: / 其它说明/ Autho

21、r: / 作者/*/举例如下：/*/ Function: StarLib_SetIdleNetIconType/ Description: 设置待机界面网络图标/ PARAM: icon:IN待机界面网络图标/ Return: 设置成功 = STARLIB_TRUE/ 设置失败 = STARLIB_FALSE/ Others: / Author: zc/*/3.4 数据注释l 【规则3-4-1】对于所有有物理含义的变量、常量，如果其命名不是充分自注释的，在声明时都必须加以注释，说明其物理含义。变量、常量、宏的注释应放在其上方相邻位置或右方。/ active statistic task num

22、ber#define MAX_ACT_TASK_NUMBER 1000#define MAX_ACT_TASK_NUMBER 1000 / active statistic task numberl 【规则3-4-2】数据结构声明(包括结构体、枚举、类等)，如果其命名不是充分自注释的，必须加以注释。对数据结构的注释应放在其上方相邻位置；对结构中每个域的注释放在该域的右方。/ sccp interface with sccp user primitive message name enum SCCP_USER_PRIMITIVE N_UNITDATA_IND, / sccp notify scc

23、p user unit data come N_NOTICE_IND, /* sccp notify user the No.7 network can not transmission this message*/ N_UNITDATA_REQ, / sccp user's unit data transmission request;l 【规则3-4-3】全局变量必须有注释，包括对其功能、取值、及其他注意事项等的说明。/标志是否通过锁卡流程；TURE = 通过锁卡流程，FALSE = 锁卡流程失败PUBLIC BOOLEAN g_isLockCardPass = FALSE;3.5

24、 代码注释l 【规则3-5-1】边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除！l 【规则3-5-2】如果代码本来就是清楚的，则不必加注释。i+; / i 加 1，多余的注释 l 【规则3-5-3】在代码的功能、意图层次上进行注释，提供有用、额外的信息。/ if receive_flag is TRUEif (receive_flag)/ if mtp receive a message from linksif (receive_flag) 无用注释 有用注释l 【规则3-5-4】注释应与其描述的代码相邻。对语句块的注释必须放在语句块上方；对单条语

25、句、变量定义的注释可以放在上方或右方（建议放在右方）；注释不可放在下方。/get replicate sub system index and net indicator repssn_ind = ssn_dataindex.repssn_index;repssn_ni = ssn_dataindex.ni;不良写法一repssn_ind = ssn_dataindex.repssn_index;repssn_ni = ssn_dataindex.ni;/get replicate sub system index and net indicator 不良写法二/ get replicate

26、sub system index and net indicator repssn_ind = ssn_dataindex.repssn_index;repssn_ni = ssn_dataindex.ni;良好的写法l 【规则3-5-5】如果注释放在上方，则将注释与其上面的代码用空行隔开。/ code one comments program code one/ code two comments program code two/code one comments program code one / code two commentsprogram code two 过于紧凑 良好写法l

27、 【规则3-5-6】避免在一行代码或表达式的中间插入注释。说明：除非必要，不应在代码或表达中间插入注释，否则容易使代码可理解性变差。l 【规则3-5-7】对于switch语句下的case语句，如果因为特殊情况需要处理完一个case后进入下一个case处理，必须在该case语句处理完、下一个case语句前加上明确的注释。说明：这样比较清楚程序编写者的意图，有效防止无故遗漏break语句。case CMD_A: ProcessA(); break;case CMD_B: ProcessB (); / 跳转到case CMD_Ccase CMD_C: ProcessC(); break;l 【规则3

28、-5-8】注释与所描述内容进行同样的缩排。说明：可使程序排版整齐，并方便注释的阅读与理解。void example_fun( void )/code one comments CodeBlock One /code two comments CodeBlock Twovoid example_fun( void ) / code one comments CodeBlock One / code two comments CodeBlock Two 不好的注释缩排 良好的注释缩排第四章 命名4.1 通用命名规则l 【规则4-1-1】标识符的命名要清晰明了，有明确含义；命名应具有描述性；一般而言

29、，类型和变量应是名词，函数应是“命令性”动词； int counter; /计数器名词NET_ICON_TYPE icon_type; / NET_ICON_TYPE 网络图标类型名词/设置IDLE页面网络图标类型“命令性”动词NET_ICON_TYPE StarLib_GetIdleNetIconType(); l 【规则4-1-2】命名应使用使用完整的单词或大家可以理解的缩写，避免使人产生误解；如使用特殊约定或缩写，要有注释说明，可参见【规则3-3】；需注意避免过度缩写。/良好命名int num_error; int num_connections;NET_TYPE StarLib_Get

30、NetWorkType();/过度缩写int nerr; int n_conns;NET_TYPE StarLib_GetNWType();4.2 文件命名l 【规则4-2】文件名全部小写；为避免由于文件名过长造成难以理解，可以在适当位置使用下划线进行分隔。不良的文件命名：mmieventmanager.h（过长难以理解） Star_HttpServer.h（含大写字母）良好的文件命名：starlib_nv.h mmi_applet_table.h mmicc_speeddial.c4.3 类型命名l 【规则4-3-1】结构体（struct）类型名遵循如下规则：每个单词首字母大写，单词间使用下

31、划线相连，以_struct后缀结束；命名中的前缀、关键缩写词等可以适当的采取全部大写。struct的typedef类型定义名遵循如下规则：和struct名采用相同命名，但全部字母大写，单词间使用下划线相连，并以_T后缀结束。一般而言，struct需同时定义类型名和typedef名。typedef struct AUDIO_Codec_Ext_CfgInfo_struct /AUDIO为前缀，采取全部大写 AUDIO_CODEC_EXT_CFGINFO_T;l 【规则4-3-2】枚举（enum）类型名遵循如下规则：每个单词首字母大写，单词间使用下划线相连，以_enum后缀结束；命名中的前缀、关键

32、缩写词等可以适当的采取全部大写。enum的typedef类型定义名遵循如下规则：和enum名采用相同命名，但全部字母大写，单词间使用下划线相连，并以_E后缀结束。一般，enum无需定义类型名，仅需定义typedef名。typedef enum Star_Tel_Type_EnumSTAR_TEL_TYPE_E;l 【规则4-3-3】函数指针（pointer to function）的typdef名遵循如下规则：单词全部字母大写，单词间使用下划线相连，以_PFUNC后缀结束。typedef void (*AUDIO_NOTIFY_CALLBACK_PFUNC)(HAUDIO hAudio, ui

33、nt32 notify_info, uint32 affix_info);4.4 变量命名l 【规则4-4-1】包括局部变量、全局变量、参数变量、成员变量，变量名一律小写，单词间使用下划线相连；命名中的前缀、关键缩写词等可以适当的采取全部大写。不良的命名：char * strTable; /大小写混杂，放弃使用该种命名方式良好的命名：AW_LCD_PARAM_T lcd_param;char nv_phone_num10;void StarLib_GetKeyRingInfo(U8 * key_type_ptr,U8 * key_vol_ptr);l 【规则4-4-2】静态全局变量使用s_前缀

34、，普通全局变量使用g_前缀。ATC_INFO_T g_atc_info_table10; /普通全局变量static BOOLEAN s_battery_status; /静态全局变量l 【规则4-4-3】对于变量命名，禁止使用单个字符（如i、j、k等）。i、j、k等仅能用作局部循环变量。单个字母唯一可使用的场合：for (i = 0; i < max; i+)4.5 常量命名l 【规则4-5-1】常量名全部字母大写。const float PI = 3.14;const int VAL_MIN = 1;4.6 函数命名l 【规则4-6-1】函数名中每个单词首字母大写；为避免由于函数名过长造成难以理解，可以在适当位置使用下划线进行分隔；命名中的前缀、关键缩写词等可以适当的采取全部大写。不良的命名：charge_init(); /未采用正确的大小写规则MMIAPICCProcessVideoCallPhoneNumExt(); /函数名太长且没有分隔，造成理解困难良好命名：Charge_Init();MMIAPICC_ProcessVideoC