代码风格与注释规范-Read.PPT

北京北清视通信息技术有限公司研发部 北京北清视通信息技术有限公司 报告人：文明 2008年1月24日星期四 编程老手与高手的误区 摘自《高质量C++/C编程指南》 自从计算机问世以来，程序设计就成了令人羡慕的职业，程序员在受人宠爱之后容易发展成为毛病特多却常能自我臭美的群体。 如今在Internet上流传的“真正”的程序员据说是这样的： 编程老手与编程高手 摘自《高质量C++/C编程指南》 定义1：能长期稳定地编写出高质量程序的程序员称为编程老手。 定义2：能长期稳定地编写出高难度、高质量程序的程序员称为编程高手。 送给软件工程师的一句话 练好兵！ C++/C代码审查表 摘自《高质量C++/C编程指南》附录A C++/C代码审查表 摘自《高质量C++/C编程指南》附录A C++/C代码审查表 摘自《高质量C++/C编程指南》附录A C++/C代码审查表 摘自《高质量C++/C编程指南》附录A C++/C代码审查表 摘自《高质量C++/C编程指南》附录A 代码使用 开发人员开始工作前要从代码库中check out代码，然后开始工作。 在check in之前要经过编译和测试，保证自己check in的代码是正确的。 每天项目负责人要对代码进行daily build，保证代码可编译，如果build失败则要追究相应人员的责任。 每天工作结束时 ，一定要将代码submit到代码库。 代码书写风格 变量命名： 允许两种风格的命名：匈牙利命名法和unix风格。 全局变量加上g_，成员变量加上m_，int32变量以i开头，int16变量以n开头，float和double以f开头，指针以p开头，后面跟上有意义的变量名。 变量不要以下划线开头。 不要使用两个只有大小写不同的变量名字。 代码书写风格 变量申明： 不要使用平台相关的申明，例如bool, byte, WORD, DWORD等，而应该使用portable.h文件定义的类型。 代码书写风格 文件命名： 均采用小写命名。 代码书写风格 指针的使用： 永远在删除后将指针设为NULL。 代码书写风格 空行 空行起着分隔程序段落的作用。空行得体（不过多也不过少）将使程序的布局更加清晰。空行不会浪费内存，虽然打印含有空行的程序是会多消耗一些纸张，但是值得。所以不要舍不得用空行。 程序员往往有两个大毛病 不愿意写注释 不写注释有什么不好？ 1）代码阅读性差，不说别人看起来不舒服，自己看起来都不顺眼。 2）难于交流，项目不是一个人做，往往是多人合作，哪怕提供SDK，也要提供容易理解的接口文件。 3）容易出错，写到后面，往往忘记了前面的，或者在调试和解决Bug时还要花很多时间去专门研究代码。 4）不是越多越好，泛滥就成灾，原则是适当的多写。 程序帮助文档有什么用？ 在我们研发过程中，有各种各样的文档，比如项目需求文档，项目设计文档，程序设计文档，协议文档等等，但是不是程序帮助文档许多人没有听说过? 程序帮助文档可以以各种方式表现程序内部结构和代码含义，这样 1）便于其同事对程序的理解。 2）便于新同事学习。 3）便于交流。 DoxyGen是什么？ 代码注释风格-头文件总体要求 原创作者名字 。 代码注释风格-文件内部注释符总体要求 DoxyGen文档注释规范 1、?模块定义（单独显示一页） /* *?@defgroup?模块名?模块的说明文字 *?@{ */ ... 定义的内容 ... /* *?@} */ DoxyGen文档注释规范 2、分组定义（在一页内分组显示） /* ?*?@name?分组说明文字 ?*?@{ ?*/ ??... 定义的内容 ... /* *?@}? */ DoxyGen文档注释规范 3、变量、宏定义、类型定义简要说明 /**?简要说明文字?*/ #define FLOAT float ? /**?@brief 简要说明文字（在前面加 @brief 是标准格式）?*/ #define MIN_UINT 0 ? /* ?*?分行的简要说明? ?*??这是第二行的简要说明 ?*/ int?b; DoxyGen文档注释规范 4、函数说明 /* ?*?简要的函数说明文字? ?*??@param?[in]?param1?参数1说明 ?*??@param?[out]?param2?参数2说明 ?*??@return?返回值说明 ?*/ int?func(int?param1,? int?param2); DoxyGen文档注释规范 /* ?* ?打开文件 ?*?? 文件打开成功后，必须使用?::CloseFile?函数关闭。 ?*??@param[in]?file_name?文件