软件编码规范文档

1、-. z.C+设计编码规V1.00试用版设备开发部 黄焕斌目录 TOC o 1-3 h z u HYPERLINK l _Toc291166485重要提示 PAGEREF _Toc291166485 h 4HYPERLINK l _Toc291166486背景 PAGEREF _Toc291166486 h 4HYPERLINK l _Toc2911664871文件组织规则 PAGEREF _Toc291166487 h 4HYPERLINK l _Toc2911664881.1命名 PAGEREF _Toc291166488 h 4HYPERLINK l _Toc2911664891.2目录

2、 PAGEREF _Toc291166489 h 4HYPERLINK l _Toc2911664901.3预处理 PAGEREF _Toc291166490 h 4HYPERLINK l _Toc2911664911.4注释 PAGEREF _Toc291166491 h 5HYPERLINK l _Toc2911664922代码组织规则 PAGEREF _Toc291166492 h 6HYPERLINK l _Toc2911664932.1空行 PAGEREF _Toc291166493 h 6HYPERLINK l _Toc2911664942.2换行 PAGEREF _Toc2911

3、66494 h 6HYPERLINK l _Toc2911664952.3空格 PAGEREF _Toc291166495 h 6HYPERLINK l _Toc2911664962.4对齐 PAGEREF _Toc291166496 h 7HYPERLINK l _Toc2911664972.5就近原则 PAGEREF _Toc291166497 h 7HYPERLINK l _Toc2911664982.6精简原则 PAGEREF _Toc291166498 h 7HYPERLINK l _Toc2911664993命名规则 PAGEREF _Toc291166499 h 9HYPERLI

4、NK l _Toc2911665003.1自注释 PAGEREF _Toc291166500 h 9HYPERLINK l _Toc2911665013.2变量 PAGEREF _Toc291166501 h 9HYPERLINK l _Toc2911665023.3函数 PAGEREF _Toc291166502 h 9HYPERLINK l _Toc2911665033.4类型 PAGEREF _Toc291166503 h 10HYPERLINK l _Toc2911665043.5宏 PAGEREF _Toc291166504 h 10HYPERLINK l _Toc291166505

5、3.6常量 PAGEREF _Toc291166505 h 10HYPERLINK l _Toc2911665064设计规则 PAGEREF _Toc291166506 h 11HYPERLINK l _Toc2911665074.1识别类和函数 PAGEREF _Toc291166507 h 11HYPERLINK l _Toc2911665084.2构造函数 PAGEREF _Toc291166508 h 11HYPERLINK l _Toc2911665094.3封装性 PAGEREF _Toc291166509 h 12HYPERLINK l _Toc2911665104.4函数参数

6、PAGEREF _Toc291166510 h 12HYPERLINK l _Toc2911665114.5函数返回值 PAGEREF _Toc291166511 h 13HYPERLINK l _Toc2911665124.6契约 PAGEREF _Toc291166512 h 13HYPERLINK l _Toc2911665134.7规模 PAGEREF _Toc291166513 h 14HYPERLINK l _Toc2911665144.8名字空间 PAGEREF _Toc291166514 h 14HYPERLINK l _Toc2911665154.9类型转换 PAGEREF

7、_Toc291166515 h 14HYPERLINK l _Toc2911665164.10常量 PAGEREF _Toc291166516 h 14HYPERLINK l _Toc2911665174.11联 PAGEREF _Toc291166517 h 14HYPERLINK l _Toc2911665184.12静态变量 PAGEREF _Toc291166518 h 14HYPERLINK l _Toc2911665194.13编译依赖 PAGEREF _Toc291166519 h 15HYPERLINK l _Toc2911665204.14可重入 PAGEREF _Toc29

8、1166520 h 15HYPERLINK l _Toc2911665215存管理规则 PAGEREF _Toc291166521 h 16HYPERLINK l _Toc2911665225.1模块化 PAGEREF _Toc291166522 h 16HYPERLINK l _Toc2911665235.2静态分配 PAGEREF _Toc291166523 h 16HYPERLINK l _Toc2911665245.3new/delete PAGEREF _Toc291166524 h 16HYPERLINK l _Toc2911665255.4有效性 PAGEREF _Toc2911

9、66525 h 16HYPERLINK l _Toc2911665265.5正确释放 PAGEREF _Toc291166526 h 16HYPERLINK l _Toc2911665275.6拷贝 PAGEREF _Toc291166527 h 16HYPERLINK l _Toc2911665286注释规则 PAGEREF _Toc291166528 h 17HYPERLINK l _Toc2911665296.1有效性 PAGEREF _Toc291166529 h 17HYPERLINK l _Toc2911665306.2普通注释 PAGEREF _Toc291166530 h 17

10、HYPERLINK l _Toc2911665316.3Do*ygen注释 PAGEREF _Toc291166531 h 17HYPERLINK l _Toc2911665326.4定义 PAGEREF _Toc291166532 h 17HYPERLINK l _Toc2911665336.5申明 PAGEREF _Toc291166533 h 18HYPERLINK l _Toc2911665346.6模块 PAGEREF _Toc291166534 h 18HYPERLINK l _Toc2911665357维护规则 PAGEREF _Toc291166535 h 19HYPERLIN

11、K l _Toc2911665367.1消除警告 PAGEREF _Toc291166536 h 19HYPERLINK l _Toc2911665377.2代码修改 PAGEREF _Toc291166537 h 19HYPERLINK l _Toc2911665387.3标本兼治 PAGEREF _Toc291166538 h 19HYPERLINK l _Toc291166539参考资料 PAGEREF _Toc291166539 h 20重要提示本规中的例如代码都在表格框中显示，绿色的表格框表示正确的例如代码，红色的表格框表示不建议的例如代码。背景C+是大华设备软件和平台软件开发的主要

12、软件，在新的软件框架里，两种平台的组件甚至是共用的。统一的代码风格，良好的设计风格，有利于代码的实现和阅读，有利于减少代码错误和提高代码效率，能有效地促进技术的交流和开展。常见的代码规都异常冗长，调调框框太多。本规力求以简明的容，概括一些重要的规则，将相似的规则进展提炼集中描述，并提供对照的例如代码加深理解。规的使用者花半个小时左右，就可以熟悉整个规。所有大华基于新软件框架的底层组件，业务组件，应用组件都必须遵守此规。例外本规是强制要求，不过有些情况例外：与第三方库有关的代码：比方stl,boost,json等等，使用、移植这些库时，相关的代码可以按照这些库的规。Windows代码：主要指基于

13、公共软件框架，同时使用了非公共组件框架的其他API接口的组件，可以继续保存Windows的规。文件组织规则命名所有的目录和文件名使用大写字母开头的单词组合，目录词之间可以用空格分开。引用文件名时要严格区分大小写。与操作系统关系密切的工程的命名可以参考操作系统的规则。Timer.cpp/源文件Timer.h/头文件Font.bin/资源文件Config1/配置文件目录一个大的工程是由多个组件或模块组成的，对于每个组件或模块，其代码应集中管理，并具备完整的设计文档和单元测试代码，用子目录分类存放。目录或文件说明Bin测试程序目录Doc设计文档目录Include依赖的组件头文件目录与本组件的外部接口

14、头文件目录，映射到其他地址Lib不同平台生成的库和依赖的库文件目录Makefile.ConfigsMakefile的不同平台的配置文件目录Src 源文件，部头文件Test单元测试代码MakefileallRules.mkMakefile文件，一次性编译Makefile.Configs目录下所有配置对应的库，测试程序预处理为了防止头文件被重复引用，使用ifndef/define/endif构造产生预处理块。预处理宏中的单词应与文件名根本一致。/文件名为Guard.h#ifndef _GUARD_H_#define _GUARD_H_/Guard类的定义.#endif /_GUARD_H_注释源文

15、件和头文件的头部都应进展注释，列出svn文件ID，申明，文件描述(说明是什么模块或什么类对应的文件)，修改记录(修改时间、svn作者、修改容)，可使用va模板。对于新参加svn的文件，应该其文件属性的svn属性列表中参加(svn:keywords, Id)属性。不要和文件中的类或模块的注释混淆。/ $Id$/ Copyright (c)1992-2007, ZheJiang Dahua Technology Stock CO.LTD./ All Rights Reserved./Description:/Revisions:Year-Month-Day SVN-Author Modificat

16、ion/代码组织规则空行类、构造、联合、函数、枚举等定义完毕后，应加空行。类定义部相关的成员变量或操作之间不加空行，其他地方应加空行。函数体，逻揖上密切相关的语句之间不加空行，其它地方应加空行。源文件和头文件末尾保存一个空行。class A;class B;换行每行代码只写一条语句。拆分复杂的复合表达式。代码行长度控制在80左右。长表达式在低优先级操作符处拆分成新行，操作符放在新行之首。 if (loadFile(m_customFilePath.c_str(), m_stream)& reader.parse(m_stream, m_configAll)& m_configAllGroups

17、.size() = 1& m_configAllUsers.size() = 1)infof(CUserManager:SetDefault() apply custom config.n);空格，之后要留空格。如果;不是一行的完毕符号，其后要留空格。二目或三目操作符前后留空格。但、.、-这类操作符和作用于分辨符:前后不加空格。修饰符*和紧靠变量名，仅在前面加空格。char *name;int *, y;/ 此处y不会被误解为指针for(int i = 0; i N; i+)对齐程序的分界符和应独占一行并且位于同一列，同时与引用它们的语句左对齐。 之的代码块使用TAB缩进并对齐，换行后的代码块

18、使用TAB缩进并对齐。代码前的注释应和所注释的代码对齐。/ment of foovoid foo()do something就近原则较为严密的代码应尽可能相邻。变量应在在定义的同时初始化。C+函数中将局部变量的定义放在要使用它的代码前最近处。将类的public接口申明放在类定义的最前面。void foo()int a = 0;a+;int b = 0;b+;精简原则DRY(Dont Repeat Yourself)系统中的每一项知识都需具有单一的表示。KISS(Keep It Simple Stupid) 保持尽量简单。类中屡次使用定义的很长的类型，应在类定义中对该类型进展更简洁自定义。访问一

19、个变量的表达式太长，应定义一个临时的指针或引用来替换它。函数中屡次调用返回结果不变的其他函数，应使用临时变量保存结果。函数中屡次引用单件，应使用临时变量甚至类的成员变量来保存单件的引用或指针。将if/else/return的组合改为return条件表达式组合。Json:Value& users = m_configAllUsers;for(uint i = pos; i draw(); /成员函数类型可直接使用bool，char等建类型，其他使用stdint.h定义的类型。算术自定义类型，类，构造，联合，枚举类型统一使用大写字母开头的单词组合。class类型的命名前加大写字母C；templat

20、e class类型的命名前加大写字母T；接口类的命名前加大写字母I。在类中嵌套的定义有具体意义的类型，是代码更易读。 typedef int Distance;union Address;enum Mode;struct User;class CPacket;template class T, class A = std:allocator class TCircularQueue;class IDevVideoEnc;宏全部使用大写字母，单词之间用下划线分开。给代码控制宏命名加上前缀，来分类不同用途的宏。以上都是指自定义的宏，不包括编译预定义宏。 # define JSON_VALUE_US

21、E_INTERNAL_MAP 1# define JSON_USE_CPPTL 1 常量防止使用常量宏，不得不使用时，参考宏的命名规则。const，枚举值等常量，应尽量作为类的成员，命名方式和变量一样。#define MA*_SIZE 10 / not so goodclass Aenumma*Size = 10;设计规则识别类和函数根本原则是高抽象性，高聚性，低耦合性。使类的接口完整并且最小。一个函数不要完成多个功能。一个变量也不能有多用途。把方法中的重复代码抽象成私有函数。尽量使用已有的函数或者标准库来实现新的函数。区分两个类A是一个B与A是B的一局部的关系，分别对应类的继承和聚合关系。/

22、 正确的设计，虽然代码冗长。class Head public: void Look(void) m_eye.Look(); void Smell(void) m_nose.Smell(); void Eat(void) m_mouth.Eat(); void Listen(void) m_ear.Listen(); private: Eye m_eye; Nose m_nose; Mouth m_mouth; Ear m_ear;如果允许Head从Eye、Nose、Mouth、Ear派生而成，则Head将自动具有Look、 Smell、Eat、Listen这些功能。例如十分简短并且运行正确，

23、但是这种设计方法却是不对的。/ 功能正确并且代码简洁，但是设计方法不对。class Head : public Eye, public Nose, public Mouth, public Ear;构造函数如果一个类可能有多个构造函数，应有公用的私有初始化函数对成员进展初始化。如果确定只有一个构造函数，应使用成员初始化列表进展初始化。并且初始化列表中成员列出的顺序和它们在类中声明的顺序一样。使用e*plicit关键字消除隐式转换class CString/ e*plicit CString(int n); / preallocate n bytesCString(const char* p);

24、CString s1 = a; / error: no implicit char-CString conversionCString s2(10); /ok: string with space for 10 characters将采用了单件实例的类或接口的构造函数和析构函数权限设置为private或protectedclass ITimerManagerpublic:static ITimerManager* instance();protected:ITimerManager();virtual ITimerManager();析构函数 确定基类有虚析构函数。拷贝函数与赋值函数 为非PO

25、D类型plain-old-data, only ints, chars, floats, or pointers, or arrays/structs of POD类声明一个拷贝构造函数和一个赋值操作符。而且在operator=中，应返回*this的引用，对所有数据成员赋值，检查给自己赋值的情况。class CZString public:CZString( const char *cstr);CZString( const CZString &other );CZString();CZString &operator =( const CZString &other )if(this = &

26、other) return *this; CZString temp(other);const char * cstr = m_cstr;m_cstr = temp.m_cstr;temp.m_cstr = cstr;private:const char *m_cstr;封装性不要重新定义继承而来的非虚函数、成员、函数的缺省参数值。防止出现public数据成员。单件模式对象构造函数应为私有类型。如果一个操作不会修改对象的属性，应该加const修饰，妥善处理const的传递性。将只与类有关的常量、类型的定义放在类的部。class Apublic:int getValue() const;priv

27、ate:int value;class Info;函数参数如果参数是一个对象，应改成传递其引用或者指针。如果参数是指针或引用，且仅作输入用，则应在类型前加const，注意值传递不用修饰。sizt_t strlen(const char * string);CRect(const CPoint &point, const CSize &size);不能计算指针形参对应的实参数组的大小已退化。函数的参数顺序应该是先输入参数，再是输出参数，同时数组的地址在前，长度在后。函数返回值不要返回栈对象的指针或引用，不要返回栈数组。Object* createObject()Object object;ret

28、urn &object;设计函数时，必须返回一个对象时不要试图返回一个引用。Object& createObject()Object object;return object;Object& createObject()Object *object = new Object;return *object;契约提供约束，宁可编译和时出错，也不要运行时出错。检查函数的前置条件，满足前置条件是调用者的责任，而被调用者假定它的前置条件已经满足。检查函数的后置条件，也就是函数返回之时哪些条件是调用者可以期望的。检查类的不变式，类的不变式确保类处于良好的状态中，一般提供一个成员函数如isValid()在函

29、数进入和退出时检查不变式。对于运行契约检查，一般使用assert，也可以采用日志记录，抛出异常等方式。/ 获取队首元素const T & front()assert(m_size 0);return m_queuem_front;不要混淆运行契约与有效代码，运行契约仅检查参数的合法性，且不应修改契约外定义的变量。assert(-m_count 0);规模函数参数个数尽量控制在5个之。函数代码尽量控制在200行代码之。每个类的平均方法数尽量控制在20个之。函数嵌套深度控制在6级之，减少没必要的递归嵌套。函数调度函数除外扇出控制在5个以。类型转换 防止强制类型转换。防止隐藏类型转换。常量C+中使用

30、const来定义常量，替换宏定义的常量。不能使用无意义的立即数。类中使用的常量应使用类的部定义的枚举类型的值。 只能使用ascii字符的字符串常量，不能使用中文等特定语言的字符串常量。联C+中应该用联函数替换宏定义的代码段。对性能要求比拟高的场合应使用联函数。使用C+标准库常用的联函数，比方ma*，min等。如果使用*函数的地方较多，而且函数体较大，不应使用联函数。 解耦合解耦合设计到很多方面，包括模块的划分，头文件依赖，模块对外的接口必须有解耦合处理，隐藏部实现的细节，防止编译依赖。如果可以使用对象的引用和指针，就要防止使用对象本身。定义*个类型的引用和指针只会涉及到这个类型的声明。定义此类

31、型的对象则需要类型定义的参与。尽可能使用类的声明，而不使用类的定义。因为在声明一个函数时，如果用到*个类，是绝对不需要这个类的定义的，即使函数是通过传值来传递和返回这个类。不要在头文件中再包含其它头文件，除非缺少了它们就不能编译。相反，要一个一个地声明所需要的类，让使用这个头文件的用户自己去包含其它的头文件，以使用户代码最终得以通过编译。 使用句柄类(Handle class)隐藏实现细节来实现解耦合。/ 编译器还是要知道这些类型名，因为Person的构造函数要用到它们class Date;class Address;class PersonImpl;class Person public:

32、Person(const string& name, const Date& birthday, const Address& addr); virtual Person(); string name() const; string birthDate() const; string address() const;private: PersonImpl *impl; / 指向具体的实现类; 除了句柄类，另一选择是使Person成为一种特殊类型的抽象基类，称为协议类Protocol class。和句柄类的用户一样，协议类的用户只是在类的接口被修改的情况下才需要重新编译。class Person

33、public: virtual Person(); virtual string name() const = 0; virtual string birthDate() const = 0; virtual string address() const = 0; virtual string nationality() const = 0;可重入对于可能被多个任务访问的资源，要使用互斥量保护，上层应用不应直接使用中断。保护的围要准确，一般使用不同的互斥量来保护不同的资源，如果整体的代价不高，也可以使用同一个互斥量。仔细考察资源之间依赖的情况，防止死锁。使用Guard守卫者来实现函数的保护，除

34、非难以使用。通过逻辑的设计，能够保证多个线程访问同一资源不会发生冲突时，可以不保护 。对于只需要自加和自减的变量可以使用AtomicCount来保证原子性。存管理规则模块化使用或者设计专有的存管理模块，而不是直接使用new/delete。给标准容器编写高效平安的allocator。 使用智能指针管理存或对象生命周期。静态分配在程序启动时从系统中静态分配好需要持续使用的存，提高性能。 new/deleteC+中使用new/delete替换malloc/free。如果重载了operator new就要同时重载operator delete。 有效性使用有效的指针及其所指向的空间，杜绝野指针。 正确

35、释放明确存块的所属对象及对象的生命周期，及时释放，防止存泄露。new出来的数组释放时也应说明它是数组。拷贝数组拷贝，或调用存拷贝、字符串拷贝接口时，应注意源区域和目标区域重叠的情况，参考memmove函数。 注释规则有效性注释的容要清楚、明了，含义准确，防止注释二义性。在代码的功能、意图层次上进展注释，提供有用、额外的信息。对于已经充分自注释程度的代码无需注释。 普通注释函数部使用C+注释风格，并在注释符号和注释容间留一个空格。注释容加在代码对象的上方或右方。if、for、do、while、case、switch、default等语句应该注释。未break的case段后面应该注释。代码块、预处理块较长的，应该注释。 Do*ygen注释函数外部使用Do*ygen C+风格注释，并在注释符号和注释容间留一个空格。注释由简要注释和详细注释组成，两者都是可选的，且是两者都不能重复。简要注释使用一行C+注释，并在开场加一个额外的斜杠，使用brief命令可以支持多行，简要注释的围将以空行或其他命令完毕。详细注释使用至少两行C+注释，每行开场加一个额外的斜杠。注释块可以加在代码对象的上面或者右方，如果加在右方，还需要加额外的符号，只有成员和参数的注释可以加在右边。一般使用简要注释即可，如需要更详