手把手教你写_“华为”_的标准注释与文档，以及代码规范

注释

---

为什么要写注释呢？为什么要写文档呢?
也许有人会这样问。但是我只想说如果你还在这样问，那么你不仅不是一个优秀的程序员，应该说你是不是程序员都应该受到质疑。

先说一下注释的重要性：
在公司的开发中，我们要明白程序不是写给自己看的，也不是所有的代码都是自己写的，我们不仅需要看别人的代码而且还要把自己的代码交给别人看，团队看。也许还会在你离职以后交给你的接班人看。而且，就算是你写的程序，如果过了很久你再去看的话（相信也会受到一万点真实伤害，脱口而出”这是哪个家伙写的这是什么东西！！！”）所以，程序文档的书写，注释的书写，以及标准的编码规范就非常的重要。（而这些是每一个大学老师都不会交给你的）

• 一般情况下，源程序的有效注释量必须在20%以上。
  说明：注释的原则是有助于对程序的阅读理解，在该加的地方都加上，注释不宜太多。也不能太少。注释语言必须准确、易懂、简洁

• 说明性文件（如头文件.h文件、inc文件、.def文件、编译说明文件.cfg等）头部应该进行注释，注释必须列出：版本说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等，头文件的注释还应有函数功能简要说明
  示例(本人的头文件头注释，当然并不局限此格式)：
  

• 源文件头部应进行注释，列出：版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。
  示例（本人源文件头注释，不局限与此格式）
  
  说明：Description一项描述本文件的内容、功能、内容各部分之间的关系及本文件与其他文件关系等。History是修改历史列表，每条记录应包括修改日期、修改人、修改内容简述等。

• 函数头部进行注释，例出：函数的目的/功能、输入参数、输出参数、返回值、调用关系（函数、表）等。
  示例：（本人的函数头注释，不局限与此格式）
  

• 我们应该养成边写代码边注释的习惯，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除