源代码书写规范

源代码书写规范源代码书写规范 1)1) 目的目的 有一个好的代码可读性；使得你读别人的代码和别人读你的代码一样容易； 避免坏的代码习惯，规范的代码不容易引进 bug，而且易于维护； 有一致的代码风格，看上去所有的代码就象一个人写的； 2)2) 声明声明 所有这些条款是强制性的，不许做任何更改，除非有明确的建议性的词语， 象“推荐” 、 “建议” 、 “试着”等； 本代码规范以 c，C+为示例，其他语言，以该语言为基础，以本规范为框 架； 3) 宗旨 代码规范的宗旨是：程序结构和可读性第一，优化第二； 4)4) 文件协定文件协定 文件的扩展名符合扩展名约定，如 C 语言文件扩展名用.c，C+扩展名用. cpp，头文件的扩展名用.h。 所有的文件必须有一个“头部分” ，描述文件功能，象接下来的样子： /* * * * 装载共享工具 * * 文件名 * * 描述本文件包括什么功能 * * (输出函数): * * (输出函数和它们的描述) * * (输出变量): * * (输出变量和它们的描述) * * */ 5)5) 函数与过程函数与过程 每一个函数必须有一个头部，用来描述函数功能，其格式象下面： -5 /* *- - * * (函数名) - * * 参数: * * (输入输出参数和它们的描述) * * 前提条件: * * (调本函数的前提条件) * * 描述: * * (函数是做什么的和函数的算法) * * 副作用: * * (任何副作用,象改变全局变量) * * 返回值: * * (返回值和它们的描述) * * 编写人和编写时间 * * 修改记录 * (每一次修改人和修改时间) *- 注意：函数头描述以“-“开始，而代替文件头描 述以“*“开始。 6)6) 代码排版代码排版 所有的全局变量，外部变量，包含头文件，都将被列出在第一个函数前； 每一个处理部分用一个该部分的注释，在每两个部分之间空一行 缩进字符数。一个 indent=4 spaces，一个 tab=8 spaces,建议用空格代替 tab； if-else ,for , while, switch 等的排版布局； 在关键字和()之间建议有一个空格 只有接下来的风格被用，除非你有一个特别原因 if (replyCode = REQ_ACCEPTED) for (ii = 0; ii = f) 7)7) 命名规则命名规则 直觉命名函数、变量、宏、常量，让它们表示它们的意思 不要用名象：aaa , foo , myOpen , myData 避免名字太短或太长，3名字长度40； 在变量、结构、函数名中，第一个单词尽量用可以反映变量类型的单词， 如 int,obj,lng,str，其余所有的单词除了第一个单词以外第一个字母将用 大写， e.g., boolFlags, intStatus, strJobLimitOk.； 类型定义(typedef)、宏(macro)、常量(constant)所有字母必须大写，单 词连接用下划线，如： e.g., LS_REQUEST_T, JOB_SYS_SUSPEND, EVENT_NEW_JOB, PEND_NOT_START_TIME 避免定义索引用数字，建议用集合定义； 避免用临时变量，象 I, ii , tmpBuf , 除了在一个局部有效，当局部外要 命名特别变量，例如： /* Find the execution host */ for (ii = 0; ii intNumHosts, ii+) if (strcmp(hostAryii.hostName, execHost) = 0) break; if (ii = numHosts) /* Cant find the execution host */ return -1; execHostIndx = ii; /* Then use execHostIndx instead of ii */ killJobOnHost(hostAryexecHostIndx, jobId); 不要用难于理解的数字，象 8、31、0x0f，用命名常量代替，除非它们用于 局部没有特别意义，象：-1 char buf32; memset(buf, 0, sizeof(buf); 避免同一块程序不同事物命名相似，例如：-1 hostNum vs numHosts 语义相似,，clientRecs vs clientReps 貌似， wrap vs rap 音似 避免不同部分、不同共用全局对象（类型、变量、宏）用相同名；-1 建议用“g”或“g_”作为全局变量前缀， “m”或“m_”作为成员前缀 （c+）或静态变量前缀（c） ，如果你愿意，可以参阅匈牙利命名规则。- -1 8)8) 注释注释 注释尽量解释、概括、描述代码的功能和内容，为什么编码用这种方法； 文件头，函数头是注释的重点； 每一个处理段至少有一个注释； 全局变量、静态变量要有注释； 每一个结构、类成员要有注释； 对每一次修改做出记录，记录修改人、修改时间、必要时注明修改原因 参考注释格式： 长格式： /* * Use information in auto.master from NIS and guess there. * replace the first component with a mount point key “/xxx“ */ if (strstr(path, “/tmp_mnt“ ) = path) 短格式： jobId = ii; /* Find a job */ 9)9) 程序的尺寸程序的尺寸 3命名的尺寸40，不要太短也不要太长； 不要把无太大关系的数据定义到结构中、类中，确保类短小精悍，继承性 强