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

1、文 档 编 号 产品版本 密级 XX产品研究部开发适用 共 页收文：X X产 品 研 究 部 软件开发人员 软件开发代码规范(仅供内部使用)拟制： 周超 日期： 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 类

2、型命名 .164.4 变量命名 .174.5 常量命名 .184.6 函数命名 .184.7 枚举命名 .184.8 宏命名.18第五章 杂项 20文件修改记录修改日期 版本修改页码、章节、条款修改描述 作者2011-4-29 0.1 创建初稿 周超2011-5-11 0.113.3数据注释4.3类型命名4.4变量命名4.6函数命名1）修改3.4数据注释 【规则 3-4-3】全局变量注释例子2）在 “4.3类型命名 ”、 “4.4变量命名” 、 “4.6函数命名”中，增加对前缀、关键缩写词等可以适当全部大写的处理。周超第一章 原则本文档的目的是提供一个公共的编码规范。这个规范详细阐述在编码时要

3、怎样写、不要怎样写，旨在提高代码的可读性、可维护性，使代码易于管理，使所有人可以集中精力去实现内容，而非处理各种复杂的表现形式。使代码易于管理的方法之一是增强代码一致性，让别人可以读懂你的代码是很重要的，保持统一编程风格意味着可以轻松根据“模式匹配” 规则推断各种符号的含义。创建通用的、必需的习惯用语和模式可以使代码更加容易理解。虽然在某些情况下改变一些编程风格可能会是好的选择，但我们还是应该遵循一致性原则，尽量不这样去做。关键在于保持一致。第二章 排版2.1 空行 【规则2-1-1】在每个函数、结构体、枚举定义结束之后都要加空行。 【规则2-1-2】在一个函数体内，逻辑密切相关的语句之间不加

4、空行，其它地方应加空行分隔。struct st1;/ 空行enum ;/ 空行void Function1()/ 空行void Function2()/ 空行while (condition)statement1;/ 空行if (condition) statement2;elsestatement3;/ 空行statement4; 函数之间的空行 函数内部的空行 【规则2-1-3】相对独立的程序块之间、变量说明之后必须加空行。if (!is_lock_card_succ). / program codeGetLockPhoneInfo(if (!is_lock_card_succ). / p

5、rogram code/空格GetLockPhoneInfo(不规范代码 规范代码2.2 代码行 【规则2-2-1】一行代码只做一件事情，如只定义一个变量，或只写一条语句。这样的代码容易阅读，并且方便于写注释。 【规则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 =

6、c + d;z = e + f;if (width =”、“” 这类操作符前后不加空格。 【建议2-3-1】对于表达式比较长的 for语句和if 语句，为了紧凑起见可以适当地去掉一些空格，如for (i=0; i= 2000) if(year=2000)if (a=b) array 5 = 0;a . Function();b - Function();良好风格 不良风格2.4 对齐缩进 【规则2-4-1】程序块要采用缩进风格编写。 【规则 2-4-2】对齐使用 TAB键，TAB 键宽度设置为 4个空格。说明：应注意使用不同编辑器时，TAB 键设置不同造成的排版不同；应注意某些编辑器在识别、显

7、示 TAB键上存在问题；最终排版应以在项目的主代码编辑器（如VC、Source Insight等）中显示一致统一、整洁清晰为准。Source Insight中设置：Options-Doucument Options-“Tab Width:4” 【规则2-4-3】函数或过程的开始、结构的定义及循环、判断等语句中的代码都要采用缩进风格，case 语句下的情况处理语句也要遵从语句缩进要求。 【规则2-4-4】程序块的分界符（如 和）应各独占一行并且位于同一列，同时与引用它们的语句左对齐。在函数体的开始、类的定义、结构的定义、枚举的定义以及if、 for、do、while、switch、case语句中

8、的程序都要采用如上的缩进方式。for (.) . / program codefor (.) . / program codeif (.) . / program codeif (.) . / program codevoid example_fun( void ). / program codevoid example_fun( void ). / program code不规范代码 规范代码 【规则 2-4-5】预处理指令不需要缩进，总是从行首开始。即使预处理指令位于缩进代码块中，指令也应从行首开始。/ 良好风格：预处理指令均从行首开始if (lopsided_score) #if DIS

9、ASTER_PENDING / Correct - Starts at beginning of lineDropEverything();#if NOTIFY NotifyClient();#endif#endifBackToNormal();/ 不良风格：缩进的预处理指令if (lopsided_score) #if DISASTER_PENDING / Wrong! The “#if“ should be at beginning of lineDropEverything();#endif / Wrong! Do not indent “#endif“BackToNormal();2.

10、5 长行拆分 【规则 2-5-1】代码行最大长度宜控制在 100至 110个字符以内。代码行不要过长，否则眼睛看不过来，也不便于打印。 【规则 2-5-2】较长的语句（ 110字符）要分成多行书写；长表达式要在低优先级操作符处拆分成新行，操作符放在新行之首（以便突出操作符） 。拆分出的新行要进行适当的缩进，使排版整齐，语句可读。 【规则2-5-3】循环、判断等语句中若有较长的表达式或语句，则要进行适应的划分. 长表达式要在低优先级操作符处划分新行，操作符放在新行之首。 【规则2-5-4】若函数或过程中的参数较长，则要进行适当的划分。if (very_longer_variable1 = ver

11、y_longer_variable12)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)n7stat_str_compare(BYTE *) 长行的拆分第三章 注释3.1 通用规则 【规则 3-1-1】一般情况，需要保证程序有一定

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

13、确的命名以及合理地组织代码的结构，使代码成为自注释的。说明：清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释。 【规则 3-1-7】注释格式尽量统一。建议使用 /进行注释，多行注释可使用“/* */”。3.2 文件注释 【规则 3-2】源文件（包含.h 头文件、.c 源文件及各种脚本文件等）头部应进行注释，应列出：版权说明、文件名、文件目的/功能，作者、创建日期等；如果源文件引入了新的缩写，则必须在文件头部注释说明。文件注释格式定义如下（可以不局限于该格式中定义的内容，但必须包含该格式中定义的内容）：/* Copyright (C) 2010-2011, XXX Co. Lt

14、d.* All rights reserved.* FileName: / 文件名称* Description: / 文件描述* 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* O

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

16、OUT 说明/ / Return: / 函数返回值说明/ Others: / 其它说明/ Author: / 作者/*/举例如下：/*/ Function: StarLib_SetIdleNetIconType/ Description: 设置待机界面网络图标/ PARAM: icon: IN 待机界面网络图标/ Return: 设置成功 = STARLIB_TRUE/ 设置失败 = STARLIB_FALSE/ Others: / Author: zc/*/3.4 数据注释 【规则 3-4-1】对于所有有物理含义的变量、常量，如果其命名不是充分自注释的，在声明时都必须加以注释，说明其物理含义

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

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

19、流程失败PUBLIC BOOLEAN g_isLockCardPass = FALSE;3.5 代码注释 【规则 3-5-1】边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除！ 【规则 3-5-2】如果代码本来就是清楚的，则不必加注释。i+; / i 加 1，多余的注释 【规则 3-5-3】在代码的功能、意图层次上进行注释，提供有用、额外的信息。/ if receive_flag is TRUEif (receive_flag)/ if mtp receive a message from linksif (receive_flag)无用注释 有用注释

20、 【规则 3-5-4】注释应与其描述的代码相邻。对语句块的注释必须放在语句块上方；对单条语句、变量定义的注释可以放在上方或右方（建议放在右方） ；注释不可放在下方。/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

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

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

23、 跳转到 case CMD_Ccase CMD_C: ProcessC(); break; 【规则 3-5-8】注释与所描述内容进行同样的缩排。说明：可使程序排版整齐，并方便注释的阅读与理解。void example_fun( void )/code one comments CodeBlock One/code two commentsCodeBlock Twovoid example_fun( void )/ code one commentsCodeBlock One/ code two comments CodeBlock Two不好的注释缩排 良好的注释缩排第四章 命名4.1 通用命

24、名规则 【规则4-1-1】标识符的命名要清晰明了，有明确含义；命名应具有描述性；一般而言，类型和变量应是名词，函数应是“命令性” 动词； int counter; /计数器名词NET_ICON_TYPE icon_type; / NET_ICON_TYPE 网络图标类型名词/设置 IDLE页面网络图标类型 “命令性”动词NET_ICON_TYPE StarLib_GetIdleNetIconType(); 【规则4-1-2】命名应使用使用完整的单词或大家可以理解的缩写，避免使人产生误解；如使用特殊约定或缩写，要有注释说明，可参见【规则3-3】；需注意避免过度缩写。/良好命名int num_er

25、ror; int num_connections;NET_TYPE StarLib_GetNetWorkType();/过度缩写int nerr; int n_conns;NET_TYPE StarLib_GetNWType();4.2 文件命名 【规则4-2】文件名全部小写；为避免由于文件名过长造成难以理解，可以在适当位置使用下划线进行分隔。不良的文件命名：mmieventmanager.h（过长难以理解） Star_HttpServer.h（含大写字母）良好的文件命名：starlib_nv.h mmi_applet_table.h mmicc_speeddial.c4.3 类型命名 【规则

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

27、下规则：每个单词首字母大写，单词间使用下划线相连，以_enum 后缀结束；命名中的前缀、关键缩写词等可以适当的采取全部大写。enum的typedef类型定义名遵循如下规则：和 enum名采用相同命名，但全部字母大写，单词间使用下划线相连，并以_E后缀结束。一般，enum无需定义类型名，仅需定义typedef 名。typedef enum Star_Tel_Type_EnumSTAR_TEL_TYPE_E; 【规则4-3-3】函数指针（ pointer to function）的typdef名遵循如下规则：单词全部字母大写，单词间使用下划线相连，以_PFUNC后缀结束。typedef void

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

29、e_ptr,U8 * key_vol_ptr); 【规则4-4-2】静态全局变量使用 s_前缀，普通全局变量使用g_前缀。ATC_INFO_T g_atc_info_table10; /普通全局变量static BOOLEAN s_battery_status; /静态全局变量 【规则4-4-3】对于变量命名，禁止使用单个字符（如i、j、k 等）。i、j、k 等仅能用作局部循环变量。单个字母唯一可使用的场合：for (i = 0; i max; i+)4.5 常量命名 【规则4-5-1】常量名全部字母大写。const float PI = 3.14;const int VAL_MIN = 1;

30、4.6 函数命名 【规则4-6-1】函数名中每个单词首字母大写；为避免由于函数名过长造成难以理解，可以在适当位置使用下划线进行分隔；命名中的前缀、关键缩写词等可以适当的采取全部大写。不良的命名：charge_init(); /未采用正确的大小写规则MMIAPICCProcessVideoCallPhoneNumExt(); /函数名太长且没有分隔，造成理解困难良好命名：Charge_Init();MMIAPICC_ProcessVideoCallPhoneNumExt(); /有适当的分隔StarLib_LiaoNingIndustry_GetAccessNumber(); /有适当的分隔4.

31、7 枚举命名 【规则4-7-1】枚举值全部大写，单词间使用下划线相连；枚举类型定义参见【规则4-3-2】 。typedef enumSTAR_STARTUP_ANIM_G3_LOGO = 0x00, /移动 G3 LOGO,默认STAR_STARTUP_ANIM_CHINA_TIETONG = 0x01, /中国铁通STAR_STARTUP_ANIM_BEIJING_MOBILE = 0x02, /北京移动STAR_STARTUP_ANIM_STARNET = 0x03, /星网锐捷STAR_STARTUP_ANIMA_MAX,STAR_STARTUP_ANIM_TYPE_E;4.8 宏命名

32、【规则4-8-1】宏命名全部大写，单词间使用下划线相连。#define STAR_DM_DES_NUM_MAX_LEN (20) /DM短信目的地址最大长度#define STAR_REAL_LCD_CONTRAST_DEFAULT (4) /液晶默认对比度第五章 杂项 【规则 5-1】所有变量定义时必须进行显式初始化。即使是全局变量、静态变量，同样要在定义进行显式初始化。/不合规范的做法static int a;int b; /规范的做法static int a = 0;int b = 0; ST_A st = 0; 【规则 5-2】为了防止头文件被重复引用（会导致类型重定义错） ，应当增加

33、包含岗哨使用 #ifndef/#define/#endif结构产生预处理块。#ifndef _STAR_LIB_H_ / 防止 StarLib.h被重复引用#define _STAR_LIB_H_#endif /_STAR_LIB_H_s 【规则 5-3】定义函数、全局变量时，必须显式说明其作用域。 由于 C语言中没有对应的关键字，可使用如下处理方式：#define PUBLIC #define LOCAL static 然后 LOCAL代表作用域为所在文件， PUBLIC代表作用域为所有文件。（为方便理解，此处使用了 “作用域 ”一词；但应知道，实际上声明的是函数 /变量的连接属性 内部连接 internal linkage/外部连接 external linkage） 。#define PUBLIC #define LOCAL static LOCAL U32 local_variable = 0;PUBLIC U32 global_variable = 0;LOCAL void local_func(void)PUBLIC void global_func(void)