资源描述
目录一般原则 2标识符 .4排版 7注视 10 采用与操作系统或开发工具的风格一致的标识符命名规则。 标识符一般由一个或多个单词组成。 变量命名禁止取单个字符。 不要仅依赖大小写来区分相似的标识符。 枚举、常量、宏的所有字母大写,用”_”分隔。 宏定义表达式时,注意使用完整的括号。 避免使用一个或两个下划线开头的标识符。 程序块要采用缩进风格编写,缩进的空格数为4个。 在循环、判断等语句中,若有较长的表达式或语句,则要进行适应的划分,操作符放在新行之首。 若函数的参数较长,则要进行适当的划分。 不要把多条语句写在一行。 if、for、while、do等语句自占一行,执行语句不得紧跟其后。不论执行语句有多少都要加。 大括号”“和“”应各独占一行并且位于关键字的同一列。 对于switch语句的每一个分支,应该有break,必须有default分支。 在二元操作符的两侧添加空格,但”.”和“-”除外。 注释的内容要清楚、明了,含义准确,防止注释二义性。 写代码的同时编写注释,修改代码同时修改相应的注释,以保证注释与代码的一致性。 注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。 注释与所描述内容进行同样的缩进排版。 注释应考虑程序易读及外观排版的因素,只使用一种语言注释代码。 在每个文件的顶部添加文件说明。一般原则 1. 编写简单的代码。 把复杂的语句和函数分解成更简单的片段。对复杂的逻辑要有明确的注释。 2. 显式的使用C/C+的特性。 避免使用C/C+的隐含特性。例如:当进行数据类型强制转换时,其数据的意义、转换后的取值等都有可能发生变化。注意运算符的优先级,并用括号明确表达式的操作顺序,避免使用默认的优先级。若是这些细节若考虑不周,就很有可能留下隐患。例如: char high, low; short word; word = high 8 | low; 应该写成: word = (short)high m_pChannel-m_pDevice-m_dwIndexInAv) & (Setting.dwWidth dwLimitedWidth | Setting.dwHeight dwLimitedHeight) ) / Do something int nAccess = WORLD_READ | GROUP_READ | | WORLD_WRITE | GROUP_WRITE | ; for (i = 0, j = 0; (i first_word_length) & (j second_word_length); i+, j+) / program code20. 若函数的参数较长,则要进行适当的划分。【必须】 void CVideoPreview:SortArea( IN const vector& StartedTaskList, IN DWORD dwDeviceIndex, OUT vector& AreaList ); n7stat_str_compare( (BYTE *)&stat_object, (BYTE *)&(act_task_tabletaskno.stat_object), sizeof(STAT_OBJECT) ); 21. 不要把多条语句写在一行。一行代码只做一件事情,如只定义一个变量,或只写一条语句。这样的代码容易阅读,并且方便于写注释。如下例子不符合规范。 int nWidth, nHeight; nWidth = 352; nHeight = 288; 应如下书写。 int nWidth; int nHeight; nWidht = 352; nHeight = 288; 22. if、for、while、do等语句自占一行,执行语句不得紧跟其后。不论执行语句有多少都要加。 这样可以防止书写失误。如下例子不符合规范: if ( NULL = pUser ) return; 应如下书写: if ( NULL = pUser ) return; 23. 大括号“”和“”应各独占一行并且位于关键字的同一列。【必须】 BOOL ExampleFun() for ( int i = 0; i ”除外。Setting.dwWidth = Setting.rcDest.right - Setting.rcDest.left; dwTotoalArea += Setting.dwWidth * Setting.dwHeight; Setting.dblScale = 1.0; 26. 一行代码保持在80个字符左右。 这样能保正代码在各种编辑器中,都能显示在屏幕中,避免了打印时换行。 27. 关键字之后要留空格。 如“if”、“for”、“while”、“catch”等关键字之后应留一个空格再跟左括号“(”,以突出关键字。 函数名之后不要留空格,而是紧跟左括号“(”,以与关键字区别。 28. if语句最好加上else分支,对没有else分支的语句要小心对待。 else分支能够保证逻辑的严谨性29. 合理的空行。 空行起着分隔程序段落的作用。空行得体(不过多也不过少)将使程序的布局更加清晰。空行不会浪费内存,虽然打印含有空行的程序是会多消耗一些纸张,但是值得。所以不要舍不得用空行。 在每个类声明之后、每个函数定义结束之后都要加空行。 在一个函数体内,逻辑上密切相关的语句之间不加空行,其它地方应加空行分隔注释 30. 注释的内容要清楚、明了,含义准确,防止注释二义性。错误的注释不但无益反而有害。31. 写代码的同时编写注释,修改代码同时修改相应的注释,以保证注释与代码的一致性。 删除已经无用注释。修改已有的代码,必须添加修改人等备注信息。 /2010-5-10, Deng Feng fixed a Blue Screen bug. /Bar3Length = BAR3_LENGTH; Bar3Length = (pde-ChipType = CHIP_HI3511) ? BAR3_LENGTH_HI3511 : BAR3_LENGTH_HI3520; /Deng Feng end. 32. 注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。#define MAX_FRAMES 1000 / Max count in the frame list #define ABANDON_FRAMES 150 / Abandon frame count / Read PCI config space from BAR5. *(PULONG)Irp-AssociatedIrp.SystemBuffer = ReadPciBar( pde, BAR5, AccessPciBar-Address ); / Set returned byte number. Irp-IoStatus.Information = (ULONG_PTR)sizeof(ULONG); 33. 注释与所描述内容进行同样的缩进排版。可使程序排版整齐,并方便注释的阅读与理解。 switch ( nSBCode ) / scroll to bottom case SB_BOTTOM: break; / scroll to top case SB_TOP: break; default: break; 34. 注释应考虑程序易读及外观排版的因素,只使用一种语言注释代码。在不影响程序易读性和外观排版的前提下,注释语言可以使用中文或英文。出于对维护人员的考虑,建议使用中文35. 在每个文件的顶部添加文件说明。下面的文件头说明比较标准,并不局限于此格式。建议下列信息要包含在内: / / Copyright (C), 2009-20XX,XXXXX. / THIS IS AN UNPUBLISHED WORK CONTAINING CONFIDENTIAL AND PROPRIETARY / / / File Name: / Author: / Version: / Date: / Description: (a brief description of the files contents) / History: (modified history) / 或者使用中文的文件头: / / 版权所有,2009-20XX,XXX公司。 / 该文件是未公开的,包含了XXXX公司机密和专利内容。 / / 文件名: / 作者: / 版本: / 日期: / 描述:(文件内容的简单描述) / 历史记录:(修改历史) / 根据文件创建的时间,确定版权时间。修订者需要更新文件的历史信息。 36. 一般情况下,源程序有效注释量必须在20%以上。 注释的原则是有助于对程序的阅读理解,在该加的地方都加上。注释不宜太多,也不能太少。注释语言必须准确、易懂、简洁。37. 通过对变量、结构、宏、函数等正确的命名以及合理地组织代码的结构,使代码成为自注释的。 清晰准确的函数、变量等的命名,可增加代码可读性,并减少不必要的注释。 38. 在代码的功能、意图层次上进行注释,提供有用、额外的信息。 注释的目的是解释代码的目的、功能和采用的方法,提供代码以外的信息,帮助读者理解代码,避免重复注释信息。如下注释意义不大。 / if receive_flag is TRUE if (receive_flag) 而如下的注释则给出了额外有用的信息。 / if mtp receive a message from links if (receive_flag) 39. 对变量的定义、分支语句、循环语句等,要编写注释。 这些语句往往是程序实现某一特定功能的关键。对于维护人员来说,良好的注释能帮助更好的理解程序,有时甚至优于看设计文档。 40. 在重要的函数前添加函数说明。 下面函数说明比较标准,并不局限于此格式。建议下列信息要包含在内: / / Function: / Description: / Parameters: (list all input and output parameters) / Return: / Remarks: / 或者用中文的函数头: / / 函数名: / 描述: / 参数:(列出所有输入、输出参数) / 返回值:/ 说明: /
展开阅读全文