Symbian C++ Coding Standards Booklet (chinese)

“Symbian 签名”由 Symbian 与其被许可公司、网 络运营商和开发者共同开发，旨在推广测试和签名 Symbian 智能手机应用程序的最佳做法。 根据开发者的反馈，为了帮助开发者开发更多的 Symbian 应用程序，我们改进了“Symbian 签名” 流程，使其更快、更容易使用和成本更低。 • 开放签名 – 免费提供在线签名流程（使用开发者 证书），以允许在由已发布 IMEI（唯一电话识别 号码）控制的多达 1000 台设备中安装和测试应 用程序。 • 快速签名 – 这是一种全新的流程，可让拥有出版 者 ID 的软件开发者对不需要利用设备敏感功能的 所有应用程序立刻进行签名，因而可将产品更快 速地推向市场。开发者现在仅需支付 20 美元即 可通过快速签名来为应用程序签名。 • 认证签名 – 用于要求利用有限制的系统能力和/或 要求独立测试的应用程序。 如需了解更多信息，请访问 www.symbiansigned.com

from

编码标准 《Symbian OS 精要》系列丛书的一部分 第 1 版：02/08 出版人： Symbian 软件有限公司 地址：2-6 Boundary Row Southwark London SE1 8HP UK（英国） www.symbian.com 商标、版权和免责条款 “Symbian OS”和其它与 Symbian 相关的标识都是 Symbian 软件有限公司 的商标。Symbian 软件有限公司承认本书中所提及的所有第三方的商标权。 Symbian 软件有限公司 2008 版权©。版权为本公司所有。本书中任何内 容未经 Symbian 软件有限公司的书面许可不得复制。Symbian 软件有限公 司对本书所含内容的恰当性与准确性不作任何保证或担保。本书的内容除 了供一般参考之用，不应该被用于任何其它目的。

编稿： Jo Stichbury 执行编辑： Ashlee Godwin

审稿： Thomas Sutcliffe Mark Shackman Hamish Willee 中文版审稿： Kelly Li

鸣谢 感谢所有多年来与我们分享诀窍和最佳作法的技术精湛和经验丰 富的软件工程师们。本手册中的许多诀窍取自于他们的集体智慧。

目录 如何使用本手册................................................................1 基本要点 ..........................................................................3 前缀 ..............................................................................3 后缀 ..............................................................................5 下划线 ..........................................................................6 大写 ..............................................................................6 头文件准则 ......................................................................7 类与函数设计 ..................................................................8 输出的函数 ....................................................................10 代码风格 ........................................................................11 构建 ................................................................................14 析构 ................................................................................14 异常处理与内存管理 ......................................................16 防御性编程 ....................................................................17 其他规则 ........................................................................18 其他阅读材料 ................................................................19 参考资料 ........................................................................20 开发者资源 ....................................................................21

1

如何使用本手册 并不是所有人都选择完全地遵循编码标准，大多数 开发者都会根据自己的经验和对 C++ 的理解在编码 时遵循一些规则。当开发者在一起工作时，他们倾 向于分享从各种来源获取的知识和最佳实践。本 《编码标准手册》旨在帮助您和您的团队定义你们 所共同发布的代码所遵循的标准。它含有一些准则， 您可以用它们来评估您的 Symbian C++ 代码的质量。 在编写代码的过程中阅读和采用这些标准，您就有 了一直保持高质量 Symbian C++ 的基础。本手册也 可被用于任何种类代码检查的参考 — 将它交给所 有检查代码的人，以确保所有人都使用同样的评估 标准。 本手册中的准则取自于 Symbian 自己和将代码提 供给 Symbian 的开发者所使用的一套广泛的 C++ 编码标准。这些标准源自于一些 Symbian 软件工 程师多年以来的经验，反映了他们的智慧和对在 Symbian OS 上使用 C++ 的理解。 Symbian 的有些标准不适用于 Symbian 以外的开 发者，所以我们没有将他们包括在本手册中，仅列 出了对广大开发者有意义的标准。本手册中所列出 的标准既适合于在 Symbian 或其被许可公司内编 写代码的开发者，又适合于大型开发机构内编写

2

Symbian 智能手机 C++ 代码的开发者和任何编写商 业或共享件售后市场应用程序的 Symbian C++ 开 发者。 应审慎地应用标准。可能会有某些准则不适用的例 外情况。在编写似乎不符合标准要求的代码时，想 一想它是否应该符合这些标准的要求。如果您和您 的同事认为你们发现了这些准则不适用的情况，请 在代码中注释。 您可能会有其他标准，例如具体的布局要求、注释 或命名惯例，除说明标准的 Symbian OS C++ 命名惯 例外，我们没有列出任何风格准则，因为我们认为 你们的代码的布局应由您和您的团队去定义。本手 册的末尾有一些空白之处，您可以在那里加入您自 己的准则和偏好。 为了让本手册可在代码检查的过程中被当作检查表 来使用，而且也因为篇幅的原因，我们在本手册中 只列出了准则，而没有进行详细地解释。您可在 Symbian 开发者网络维客网址 (developer.symbian.com/coding_standards_wikipag e) 看到更多有关准则的讨论。

3

基本要点 1.

编写时不发出警报。将编译器设置成最高警报 级别，干净地编写您的代码，以确保它不发出 警报。如果发出了警报，一定要了解其中的原 因，即使代码在产生警报时仍在正常运行，我 们仍需更改代码来消除警报。

2. 遵循 Symbian OS 命名惯例。如果所有团队成员 均在他们的代码中遵循同样的命名惯例，则代 码就可更容易地被分享和维护，因为它可立刻 被人们所理解。这也适用于由一个完全不同的 团队生成的代码，例如一个公用程序库 (utility library) 或在 Symbian OS 上使用的 SDK。 Symbian 及其被许可公司在命名类、变量和函数 名称时使用了一套具体的规则，所以使用这些 开发工具的人可容易地理解如何使用所提供的 API 和范例代码。

前缀 成员变量前加上一个小写的 ‘i’（代表“实例”）作 前缀，例如：

4 TInt iCount; CBackground* iBitmap;

参数前加上一个小写的 ‘a ’（代表“变元”）作为前 缀。对于以元音字母开始的变元，我们不使用 ‘an’。 例如： void ExampleFunction(TBool aExampleBool, const TDesC& aName);

(注意：是 TBool aExampleBool 而不是 TBool anExampleBool。) 局部变量无前缀。例如： TInt localVariable; CMyClass* ptr = NULL;

类名应使用与其 Symbian OS 类型相符的字母做前 缀，通常为 C、R、T 或 M，仅由静态成员函数组成时 除外。 （请参阅 Symbian 出版社系列丛书或 Symbian Developer Library 详细了解每种 Symbian OS 的特 性)。例如： class class class class

CActive; TParse; RFs; MCallback;

5

常量加 ‘K’ 作为前缀。例如： const TInt KMaxFilenameLength = 256; #define KMaxFilenameLength 256

枚举为简单类型，所以加 ‘ T ’ 作为前缀。枚举成员 加 ‘E’ 作为前缀。例如： enum TWeekday {EMonday, ETuesday, ...};

将一个成员变量设为一个值的成员函数命名为 SetXxx()。检索成员变量的值作为引用参数的成员 函数命名为 GetXxx()。返回成员变量的值的成员函 数命名为 Xxx()。例如： void SetSpeed(TInt aSpeed); void GetSpeed(TInt& aSpeed) const; TInt Speed() const;

后缀 函数名的后缀 ‘L’ 表示函数可能会异常退出。例如： void AllocL();

6

相反，在命名函数时不加后缀 ‘L’，你实际上在向所 有调用这一函数的人保证函数永远不会异常退出。 函数名的 ‘ C ’ 后缀表示函数返回了被推向清除栈的 一个指针。例如： static CCylon* NewLC();

函数名的 ‘D’ 后缀表明它将删除函数所引用的对象。 例如： TInt ExecuteLD(TInt aResourceId);

下划线 除了宏(__ASSERT_DEBUG)或资源文件(MENU_ITEM) 外，名字中避免使用下划线。

大写 类名的首字母为大写，例如： class TColor;

7

组成变量名、类名或函数名的单词连在一起，每一 单词的首字母大写。类和函数的首字母大写，而函 数参数、局部、全局和成员变量的首字母小写。 除每一单词的首字母外（如恰当） ，每一单词的其 余字母为小写，包括缩写词。例如： void CalculateScore(TInt aCorrectAnswers, TInt aQuestionsAnswered); class CActiveScheduler; TInt localVariable; CShape* iShape; class CBbc;// Acronyms are not usually // written in upper case

宏的名称仅使用大写字母，用下划线将每个单词 分开。

头文件准则 3. 头文件应“自足”，可自编，包含其内容所需要 的任何头部。包含头部的代码不应也必须包括 其他内容才可编写。

8

4. 头文件只能包含绝对必要的头部。在恰当的情 况下，最好使用前置引用来减少所包含的头数。 5. 应使用包含保护符来避免包含多个头部。例如： #ifndef GAME_ENGINE_H__ #define GAME_ENGINE_H__ ...

// Header file code goes here

#endif // GAME_ENGINE_H__

类与函数设计 6. M 类仅应用于指定接口，而不是实现，一般应 仅包括纯虚函数 7. 仅通过 M 类所定义的接口使用多继承。从一个 CBase 派生类和一个或多个 M 类继承 (CBase 派 生类应在继承列表中首先出现，以确保清除栈 能够正确进行析构)。 8. 应避免私有继承，少数情况除外。最好使用 复合。

9

9. 枚举应在与它们相关的类或命名空间中有效， 不能在全局都有效（除非要求这样做），以避免 污染全局的命名空间。 10. 在类设计中，应使用重载函数，而不是缺省参 数。 11. 虚函数不能内联(虚内联析构器除外)。 12. 对 于 应 内 联 的 函 数 ， 应 明 确 指 定 i n l i n e 关 键词。 13. 在函数中，一般应使用引用参数，而不是指针， 除非所有权转换或参数可以为 NULL 时（这时必 须使用指针） 。 14. 在函数中，如数据未计划进行修订，则参数和 返回值应总是使用 const 说明符。 15. 在函数中，传值仅可用于基本数据类型或小型 Symbian OS T 类对象(<8 字节)。传引用应用于大 型对象(≥8 字节)。

10

输出的函数 16. 头文件声明带 IMPORT_C 标签的每个函数均必须 让其实现带 EXPORT_C 标签。 17. 数据不应被输出，应提供一个修订它的函数 （一种 Set()方法）或将其通过引用返回以便进 行修订（如恰当）。 18. 仅可在以下情况时输出私有函数： (i)

公共内联成员在访问它们时

(ii) 它们是虚拟的，类计划来自代码内，代码 不是 输出模块的一部分。 19. 在以下情况不应输出公共或受保护的函数： (i)

它们并未被设计成在库外使用

(ii) 它们为纯虚函数。 20. 无论是公共、受保护还是私有，内联函数均不 应被输出。

11

代码风格 21. 为了提高效率，在构建器中初始化成员变量时， 应使用成员初始化列表，而不是赋值语句。 22. C 类的成员数据不需要显式初始化至零。 23. 在测试 Booleans 时，不要使用显式比较。应使 用 if(iComplete)，而不使用 if(iComplete==ETrue)。 24. 在测试 NULL 的指针值时，除非完整写出比较可 让代码的意图更清楚，则无需使用明示比较， 应使用 if(ptr)，而不是 if(ptr!=NULL)。 25. 在 测 试 i n t e g e r s 时 应 使 用 明 示 比 较 ： 使 用 if(aLength!=0)，而不是 if(aLength)。 26. 为了避免范围膨胀，除非有要求否则不要声明 自动变量，而且声明时应尽可能靠近其使用点。 27. 应尽量不使用堆栈，尤其不使用堆栈来存储大 型数据架构，而且在循环或递归函数内声明大 型基于栈的变量时要十分小心。使用 TFileName 和 TParse 类通常都是消耗堆栈的原因，因为这 两种类的对象的大小都在 512 字节以上(缺省堆 栈的大小仅为 8KB)。

12

28. 应避免硬编码魔数。而应使用常量或枚举。 29. 应使用 e32def.h 内所定义的具体类型，而不使 用语言定义的基本类型。例如，应使用 TInt ， 而不使用 int。 30. 应使用 Symbian OS 描述符类，而不使用本地字 符串和内存缓冲或其他手动制成的字符串类。 31. 除了在测试码中为方便时使用之外，文字描述 符不应使用 _L 宏，应使用 _LIT 宏。 32. 在使用描述符作为函数参数时，应使用基类 (TDes 和 TDesC)，应为传引用。 33. 应使用 Symbian OS 日期和时间类 （例如 TDateTime 和 TTime ），而不应使用手工 制作的其他类。 34. 在 switch 语句中，在 case 语句中使用贯穿时 应进行注释来传达意图。switch 语句应总是含 有一个 default 语句，即使它的唯一目的只是 声明它从未被到达。

13

35. 应使用 C++ 风格强制转换 （例如 static_cast(expression)）， 而不使用 C 风格强制转换。不应在 C++ 强制转 换操作符中使用我们不赞成使用的 Symbian OS 宏（例如 STATIC_CAST(type, expression))。 36. 循环中的代码对于所有可能的输入均应终止。 37. 模板代码应使用薄模板，以确保收益于 C++ 模 板的优势的同时代码的规模尽量小。 38. 在可能的情况下，在 DLL 中应避免使用可写全 局数据。

14

构建 39. C++ 构建器中的代码不应异常退出。 40. 异常和可失效的构建与初始化代码通常应在 两阶段构建器的第二阶段按 ConstructL()方法 实施。 41. 在进行两阶段构建时，应提供一个或多个公共 静态工厂函数（通常叫作 NewL() 和 NewLC()） 来构建对象。构建方法本身应为私有或受到 保护。

析构 42. 在析构器中解除一个指针的引用时，应首先检 查指针是否有效，以防它还没有被初始化或它 已经被继承结构中的另一个析构器析构。 43. 除非它有可能会在析构过程中在其他地方被解 除引用，例如在一个超类中的析构器中，将指 针在析构器中设为 NULL 是低效和不必要的。 44. 在析构器外被删除且可在以后被访问的指针 （例如成员变量指针）应被设为 NULL 或立刻被 重新分配。

15

45. 析构器中的资源句柄和基于堆栈的成员数据如 由一个类拥有就应被清除 46. 析 构 器 不 能 异 常 退 出 或 抛 出 任 何 类 型 的 C + + 异常。 47. 可在堆上存储的类的析构器中使用 TRAP，但在 堆栈展开时可能会调用的析构器中使用 TRAP 会 不安全。 48. 如对象被清除，则它不应在清除栈上。 49. 如 对 象 被 调 用 分 配 给 n e w ， 则 它 应 通 过 调 用 delete