C编码规范(Ver0.1).doc

C+编码规范(Ver 0.1)文档历史修订日期修订内容修订版本修订人2006-7-4初始版.10EVA2006-7-12STL PORT ，跨dll编程,assert.11PUZZY2006-7-19STLPORT 5 更新.12PUZZYSTLPORT 5更新STLPORT5 支持vc71和vc8 。新项目建议使用vc8（vc2005）。 需要的头文件和LIB放在122/horizon/STLPORT5.0.2/目录下。StlPort与BoundChecker兼容当BoundChecker与STLPORT一起使用时，会因为stlport使用vector内存池，以及replacement new，而误报内存泄露等错误。解决方法：1，当使用BoundChecker时，把系统目录设置成VC自带的stl目录。2，当需要stlport与BoundChecker一起使用时，需要改变STLPORT配置后，重新编译stlport。步骤：A,修改stlport/stl/_config.h ，在39行左右（最前面）加上” #define _STLP_DONT_USE_SHORT_STRING_OPTIM 1 ”B,修改 _site_config.h ，在123行左右，“#define _STLP_USE_NEWALLOC 1”和 “#define _STLP_USE_MALLOC 1”这样编译后的版本，无法使用stlport对string的优化，以及自己的malloc和new。意义没有方法1大STLPORT 使用规范1，综述STL PORT 具有对所有容器进行越界检查， 遍历器归属，有效性，算法条件检查等各种安全检查。所以H3D工程使用STLPORT作为标准库。 STL PORT 在vc2003/05中，需要使用自己的stream静态链接库。 *.lib已提供。2， 使用在vc-tools-options-project-VC+ directories-, 把STL PORT的include , lib目录， 分别设置在VC系统include 和 lib目录的前面。3， 配置需要打开STL PORT DEBUG功能时，在项目属性-C/C+-PreProcessor-Preprocessor Definitions- 增加 _STLP_DEBUG.跨DLL编程事项1， 不得提供带有stl参数的接口函数2， 不得同时在两个DLL对一个局部HEAP进行操作，例如： 在一个DLL里new的指针，在另外一个DLL内deleteASSERT定义使用： assert_custom(bool b)if (b=false) _asmint 3; 重新定义assert内存检测必须使用memory manager对内存进行检测。 严格控制new 以及生命对象周期。 书写new的同时，必须先构造好delete的函数。在所有出现new和delete的地方，加入 memory manager头文件。STL PORT和MEMORY MANAGER放在 192.168.0.122/share/Horizon普适原则1.直白式的代码比起注释来的更有意义2.Coders不能为了图方便而牺牲了代码的健壮性和可理解性3.格式化规则应当明白直接,花时间考虑如何格式化代码比多花时间编码更有用4.规则应该防范那些会引发微妙错误的代码5.应该避免无意义的过于烦琐的规则1.文件及预处理器1.1 需要有统一的格式来进行文件头的编写，法律以及更改日志在版本没有稳定前只需留出位置不需要填写内容。具体统一格式下一版中出。1.2在头文件中使用#includeguards防止被include多次.(就是#ifndefxxx_hpp#definexxx_hpp#endif)。如何使用guards（#if ！defined vs #ifndef）下一版给出。1.3Cpp源程序应该最开始#include的头文件必须是其对应的头文件， 如果无法编译应该改变其对应的头文件。1.4#include一律出现在文件开头,如果是头文件放在#includeguards之后的开头1.5尽量避免头文件依赖，如果某个头文件中需要用到某个类的引用或指针,那么只需要一个forwarddeclaration就足够了。如：class Renderer;Renderer* a;Renderer& b;在使用模块时，为了避免过于繁琐的指定所需要的模块中的头文件，可以使用由模块提供的一个功能头文件，这个头文件将包含模块定义的所有头文件。这个头文件由模块编写者提供。1.6使用相对#include路径.目录结构最好和工程的namespace结构类似推荐避免定义预处理的宏特别是在头文件中(规则1.2例外),请使用enum,const,function,template等避免宏的定义.如：用enum MusicNum = 12 或 const int MusicNum = 12而不是#define MusicNum 12用inline max(int a, int b)或template max(const A& a, const A& b)而不是#define max(a, b) 2命名2.1类成员变量要使用比较能够明确表意的名字，局部变量名可以简略。类成员变量与局部变量名在命名上要有区别。如（非要求），类成员变量为m_hit_count; 局部变量名hc2.2具有改变状态的函数,应当是E文中的动词短语2.3在命名中避免trademark，如h3d, kart_2.4短名字应当依照通用惯例.如ijk用于循环控制变量,pq用于指针和遍历子2.5预处理宏应尽量避免无法避免的时候,它的命名应当是全大写形式,头文件中使用的宏要么就取一个奇长无比的名字,要么就在使用以后#undef掉(避免名字污染)推荐选择表示目的的名字而不是表示实现的名字,比如定义一个已知设备列表使用list known_devices;而不是list device_list.布尔变量和布尔函数应当是E文中的谓词短语这样条件语句读起来就好像是E文中的条件句了.如if(buffer-is_empty()描述对象状态的函数应当是名词短语如得到container长度的函数应叫size()而不是get_size()尽量不使用带有双下划线_,或是以单下滑线_开头的名字3 空格及空行3.1单目前缀运算符不能紧跟有空格如*p,!is_right；单目后缀运算符不能有前导空格如f(),a,i+；-前后都不能有空格3.2对于空格与空行，不同人的风格差异很大，不做特别细致的要求； 但要求每个单一文件中使用的空格和空行风格必须相同。3.3对于组合的位运算，写全括号if(a & 0x01) / okif(a & 0x01 & b) / badif(a & 0x01) & b) / server3.4如果表达式要分开多行,请在某个运算符之前分行这样下一行很明显能看出是上一行的继续如intb=a+2;4 缩进4.1对于缩进，不同人的风格差异很大，不做特别细致的要求； 但要求每个单一文件中使用的缩进风格必须相同5.块和语句的格式化5.1和单独占用一行5.2和应和该块代码的前一行代码具有相同的缩进5.3附属的流程控制子语句使用单独的行不要这样写if(.)do_something;5.4多行的附属子语句前后必须加和如if(.)/oneline/another推荐如果if子句加了,else字句也要加,反过来也一样6.声明和初始化6.1指针和引用一行只能声明一个名字int* a; / okint& b/ okfloat x, y, z; / okint a, *b, &c; / bad6.2将*,&和类型名放在一起,不要和对象名放在一起(如写成int*p,而不是int*p)6.3尽可能晚的定义局部变量，并赋初值6.4复用一个变量时不要出于不同的目的.复用变量并不会节约资源,编译器知道一个变量什么时候没有用了.相反复用变量会把读代码的人搞糊涂.推荐尽可能的使用const.看的人清楚,用的人也明白,使用错误时编译器还能报错7. 注释7.1长注释应和代码分在不同的行7.2函数的注释放在一处,不用在声明和定义两边都写7.3对于每一个虚函数,在还没有被继承的地方注释注释包括该函数会在何时被调用,如何被调用,什么时候会需要重载它.对于非纯虚函数,写出它缺省实现的效果7.4 使用标准的C+术语，如类成员函数，而不是方法，是类成员变量，而不是属性。推荐注释所有的public和protected成员函数的声明.那些具有特定意义的函数如拷贝构造函数,拷贝赋值运算符,析构函数就不用了所有其它函数(private的非虚函数,在无名namespace中定义的函数)应该在定义的地方写下它的注释.这是为了避免在头文件中留下实现细节的描述8.类的组织8.1在继承类里也重复写virtual关键字, 让别人清楚知道函数的类型9.继承和运行时多态10.组件文档10.1在每一个组件之前使用一段注释描述它的界面(组件是一个,或是一组具有相关功能的类和函数的集合,通常存在于一个头文件中)10.2注释的内容应该是描述该组件是什么,应该如何使用该组件10.3为继承类的实现者在共有接口部分写好详细的文档.(避免错误的继承)10.4模版的注释文档应当列出在模版(类/函数)的实现中用到了模版参数的那些操作.10.5实现细节文档应该与共有接口注释和继承接口注释分开,最好不要放在头文件中,并包含一个简练,完整的classinvariants(类的不变式)的列表11.错误处理和健壮性推荐使用assert()(或是适当的代替品)来检测是否有未满足的precondition(前提)和编程错误.前提是函数执行前必须为真的一个条件.12.名字空间Namespaces推荐将你所有的代码放入名字空间中每一个子模块都应成为一个单独的子名字空间当访问别的名字空间的名字时,最好使用显示限定(而不是在使用前加using)避免使用using指示符避免导入标准C头文件将只用于该文件的名字放入无名名字空间(namspace.),这样就不会和其它源文件中的名字冲突13.重载Overloading13.1不同的重载函数应当具有相同的语意13.2运算符重载应当符合既定习惯13.3避免重载虚函数推荐为保证常量正确性添加重载函数当函数返回它的某个参数的non-constreference或iterator(或*this)的时候,应当有相应的一个函数返回constreference或iterator如：const Render* getRender() const;Render* getRender();14.类型转换14.1了解那种转换更加安全.dynamic_cast比static_cast安全,static_cast和const_cast和reinterpret_cast比C风格的转换都要安全推荐尽量不使用隐式类型转换15.杂项Miscellaneous15.1尽量使用标准库推荐不要使用接受可变参数个数的函数(likeprintf),因为它们不是类型安全的类的成员变量尽量不要使用引用类型class Aint& m_t; / badpublic:A(int& r) : m_t(r) / bad;实际工程中必须要注意的地方内存的分配与释放，必须在同一个dll/exe中进行不要进行标准库容器（包括string）的传递再做操作时要先判断或断言操作的参数是否合法erase(pos) / assert(pos ！= end() vectoridx / assert(idx = 0)尽量避免魔数（MAGIC NUM）特别审视数组越界以及标准库的使用方法int A12; A12 = 0; / badBuffer L; / 删除容器中若干符合条件的元素FO