1 / 32

北京北清视通信息技术有限公司

北京北清视通信息技术有限公司. 代码风格与注释规范. 报告人：文明 2008 年 1 月 24 日星期四. 编程老手与高手的误区 摘自 《 高质量 C++/C 编程指南 》. 自从计算机问世以来，程序设计就成了令人羡慕的职业，程序员在受人宠爱之后容易发展成为毛病特多却常能自我臭美的群体。 如今在 Internet 上流传的“真正”的程序员据说是这样的：. 真正的程序员没有进度表，只有讨好领导的马屁精才有进度表，真正的程序员会让领导提心吊胆。. 真正的程序员不写使用说明书，用户应当自己去猜想程序的功能。.

tavon
Download Presentation

北京北清视通信息技术有限公司

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. 北京北清视通信息技术有限公司 代码风格与注释规范 报告人：文明 2008年1月24日星期四

  2. 编程老手与高手的误区 摘自《高质量C++/C编程指南》 自从计算机问世以来，程序设计就成了令人羡慕的职业，程序员在受人宠爱之后容易发展成为毛病特多却常能自我臭美的群体。 如今在Internet上流传的“真正”的程序员据说是这样的： 真正的程序员没有进度表，只有讨好领导的马屁精才有进度表，真正的程序员会让领导提心吊胆。 真正的程序员不写使用说明书，用户应当自己去猜想程序的功能。 真正的程序员的程序不会在第一次就正确运行，但是他们愿意守着机器进行若干个30小时的调试改错。 真正的程序员不接受团队开发的理念，除非他自己是头头。 真正的程序员几乎不写代码的注释，如果注释很难写，它理所当然也很难读。 真正的程序员不写文档也不需要文档，只有看不懂程序的笨蛋才用文档。 北京北清视通信息技术有限公司研发部

  3. 编程老手与编程高手 摘自《高质量C++/C编程指南》 • 定义1：能长期稳定地编写出高质量程序的程序员称为编程老手。 • 定义2：能长期稳定地编写出高难度、高质量程序的程序员称为编程高手。 北京北清视通信息技术有限公司研发部

  4. 送给软件工程师的一句话 • 练好兵！ 北京北清视通信息技术有限公司研发部

  5. C++/C代码审查表 摘自《高质量C++/C编程指南》附录A 北京北清视通信息技术有限公司研发部

  6. C++/C代码审查表 摘自《高质量C++/C编程指南》附录A 北京北清视通信息技术有限公司研发部

  7. C++/C代码审查表 摘自《高质量C++/C编程指南》附录A 北京北清视通信息技术有限公司研发部

  8. C++/C代码审查表 摘自《高质量C++/C编程指南》附录A 北京北清视通信息技术有限公司研发部

  9. C++/C代码审查表 摘自《高质量C++/C编程指南》附录A 北京北清视通信息技术有限公司研发部

  10. 代码使用 • 开发人员开始工作前要从代码库中check out代码，然后开始工作。 • 在check in之前要经过编译和测试，保证自己check in的代码是正确的。 • 每天项目负责人要对代码进行daily build，保证代码可编译，如果build失败则要追究相应人员的责任。 • 每天工作结束时 ，一定要将代码submit到代码库。 北京北清视通信息技术有限公司研发部

  11. 代码书写风格 • 变量命名： • 允许两种风格的命名：匈牙利命名法和unix风格。 • 全局变量加上g_，成员变量加上m_，int32变量以i开头，int16变量以n开头，float和double以f开头，指针以p开头，后面跟上有意义的变量名。 • 变量不要以下划线开头。 • 不要使用两个只有大小写不同的变量名字。 北京北清视通信息技术有限公司研发部

  12. 代码书写风格 • 变量申明： • 不要使用平台相关的申明，例如bool, byte, WORD, DWORD等，而应该使用portable.h文件定义的类型。 • 循环变量： • 使用i, j, k, l, m作为循环计数变量。 • 使用括号： • 在对运算优先级没有把握的地方使用括号，建议尽量使用括号。 北京北清视通信息技术有限公司研发部

  13. 代码书写风格 • 文件命名： • 均采用小写命名。 • 循环： • 使用正确的循环。如果代码最少要执行一次，使用do-while循环，否则使用while-do循环。如果确切的循环执行次数已知，使用for循环。 • 变量初始化： • 初始化必要的变量，特别是静态变量应该显式初始化，因为有些编译器不支持将静态变量初始化。 北京北清视通信息技术有限公司研发部

  14. 代码书写风格 • 指针的使用： • 永远在删除后将指针设为NULL。 • 函数申明和定义： • 对于其他文件和模块要调用的函数一定要在头文件声明它，对于仅在本文件使用的函数需要在定义的时候增加static关键字。 • 对于有返回值的函数一定要保证在每一条退出路径都有返回值，以免引起随机错误，对于这一情况，编译器会给出警告。 • 重视编译警告： • 作为一个程序员应该尽可能的减少警告的数量。 北京北清视通信息技术有限公司研发部

  15. 代码书写风格 • 空行 • 空行起着分隔程序段落的作用。空行得体（不过多也不过少）将使程序的布局更加清晰。空行不会浪费内存，虽然打印含有空行的程序是会多消耗一些纸张，但是值得。所以不要舍不得用空行。 • 缩进 • 如果仅仅在Windows系统，可以用Tab缩进，如果要在Linux中使用Vi，Emacs等，推荐用空格缩进，一般以两个空格为单位。 北京北清视通信息技术有限公司研发部

  16. 程序员往往有两个大毛病 • 不愿意写注释 • 从来不写程序帮助文档 北京北清视通信息技术有限公司研发部

  17. 不写注释有什么不好？ • 1）代码阅读性差，不说别人看起来不舒服，自己看起来都不顺眼。 • 2）难于交流，项目不是一个人做，往往是多人合作，哪怕提供SDK，也要提供容易理解的接口文件。 • 3）容易出错，写到后面，往往忘记了前面的，或者在调试和解决Bug时还要花很多时间去专门研究代码。 • 4）不是越多越好，泛滥就成灾，原则是适当的多写。 北京北清视通信息技术有限公司研发部

  18. 程序帮助文档有什么用？ 在我们研发过程中，有各种各样的文档，比如项目需求文档，项目设计文档，程序设计文档，协议文档等等，但是不是程序帮助文档许多人没有听说过? 程序帮助文档可以以各种方式表现程序内部结构和代码含义，这样 • 1）便于其同事对程序的理解。 • 2）便于新同事学习。 • 3）便于交流。 北京北清视通信息技术有限公司研发部

  19. DoxyGen是什么？ • Doxygen 是一个程序的文档生成工具，可将程序中的注释转换成为说明文档。DoxyGen分为两大部分，一为特定的注释规范，即DoxyGen注释规范，二为将程序转换为文档的DoxyGen工具。 • 目前Doxygen可处理的程序语言包含 • C/C++、Java、IDL (Corba, Microsoft及KDE-DCOP类型) 等  • 可产生出来的文件格式有 • HTML 、XML、LaTeX、RTF、Unix Man Page等   北京北清视通信息技术有限公司研发部

  20. 代码注释风格-头文件总体要求 • 原创作者名字 。 • 原始创建日期。 • 文件的用途 。 • 修订历史记录，同时应该说明修订时发现并修复的bug。 北京北清视通信息技术有限公司研发部

  21. 代码注释风格-文件内部注释符总体要求 • 程序中的注释，尽量使用中文书写。 • 程序中的注释不能过于简单，要能让阅读者理解。 • 原则上，每个程序函数和模块都必须给出注释；大段注释应该在函数或模块定义之前书写。 • 程序中使用特定算法的位置，必须给出算法的详细描述。 • 程序的注释必须和相应代码放在文件的相同位置，不得分别维护。 北京北清视通信息技术有限公司研发部

  22. DoxyGen文档注释规范 • 1、 模块定义（单独显示一页） • /* • * @defgroup 模块名 模块的说明文字 • * @{ • */ • ... 定义的内容 ... • /* • * @} • */ 北京北清视通信息技术有限公司研发部

  23. DoxyGen文档注释规范 • 2、分组定义（在一页内分组显示） • /* •  * @name 分组说明文字 •  * @{ •  */ •   ... 定义的内容 ... • /* • * @}  • */ 北京北清视通信息技术有限公司研发部

  24. DoxyGen文档注释规范 • 3、变量、宏定义、类型定义简要说明 • /** 简要说明文字 */ • #define FLOAT float • /** @brief 简要说明文字（在前面加 @brief 是标准格式） */ • #define MIN_UINT 0 • /* •  * 分行的简要说明  •  *  这是第二行的简要说明 •  */ • int b; 北京北清视通信息技术有限公司研发部

  25. DoxyGen文档注释规范 • 4、函数说明 • /* •  * 简要的函数说明文字  •  *  @param [in] param1 参数1说明 •  *  @param [out] param2 参数2说明 •  *  @return 返回值说明 •  */ • int func(int param1,  int param2); 北京北清视通信息技术有限公司研发部

  26. DoxyGen文档注释规范 • /* •  *  打开文件 •  *   文件打开成功后，必须使用 ::CloseFile 函数关闭。 •  *  @param[in] file_name 文件名字符串 •  *  @param[in] file_mode 模式字符串，可由以下几个模块组合而成： •  *  - r 读取 •  *  - w 可写 •  *  - a 添加 •  *  - t 文本模式(不能与 b 联用) •  *  - b 二进制模式(不能与 t 联用) •  *  @return 返回文件编号 •  *  - -1 表示打开文件失败 •  *  •  *  @see ::ReadFile ::WriteFile ::CloseFile •  *  @deprecated 由于特殊的原因，这个函数可能会在将来的版本中取消。 •  */ • int OpenFile(const char* file_name,  const char* file_mode); 北京北清视通信息技术有限公司研发部

  27. DoxyGen文档注释规范 • 5、枚举类型定义 • /** 枚举常量 */ • typedef enum TDayOfWeek • { • SUN = 0,  /**<  星期天（注意，要以 “<” 小于号开头） */ • MON = 1,  /**<  星期一 */ • TUE = 2,  /**<  星期二 */ • WED = 3,  /**<  星期三 */ • THU = 4,  /**<  星期四 */ • FRI = 5, /**<  星期五 */ • SAT = 6   /**<  星期六 */ • } • /** 定义类型 TEnumDayOfWeek */ • TEnumDayOfWeek;   北京北清视通信息技术有限公司研发部

  28. DoxyGen文档注释规范 • 常用的DoxyGen标记：brief，name，param，return，file，version，date，author等 北京北清视通信息技术有限公司研发部

  29. 使用DoxyGen工具生成文档 • 1）到http://www.doxygen.org/下载DoxyGen并安装。 • 2）准备好源文件。 • 3）运行DoxyGen生成源文件的相应文档。 • 留做课后作业！ 北京北清视通信息技术有限公司研发部

  30. DoxyGen例程 • doxygenExample.h • deque.h • deque.c 北京北清视通信息技术有限公司研发部

  31. 代码风格与注释规范目标是什么？ • 目标 • 1）按照研发部编码规范形成良好统一的编码风格。 • 2）按照DoxyGen注释规范形成良好统一的注释风格。 • 3）在需要的时候，用DoxyGen生成程序帮助文档。 写代码就如同书法，要做到入木三分，行云流水般，那才是最高境界！ 北京北清视通信息技术有限公司研发部

  32. 代码风格与注释规范 报告完毕！谢谢！ 北京北清视通信息技术有限公司研发部

More Related