代码注释规范

目的

• 注释是为了让读代码的人和写代码的人对代码的了解一样多
• 随着鱼塘业务复杂性的增加，代码中关于业务的内容不应只存在于写代码的人脑子里，而应该通过注释保留在代码中
• 提高代码的可维护性，减少团队协作的沟通成本

原则

• 注释应注重”为何做（why）“而不是”怎么做（how）“
• 如果你发现自己需要写注释，再想想是否有办法翻盘，用代码来表达，很多时候，只要创建一个描述与注释所言同一事物的函数即可；如果最终决定要写注释，就要花必要的时间确保写出最好的注释ÏÏ
• 注释存在的时间越久，就离其所描述的代码越远，越来越变得全然错误；因此，程序员应当负责将注释保持在可维护、有关联、精确的高度

注释的种类

类别	内容/目的	优劣
重复性注释	只是用不同文字把代码的工作又描述一次	除了增加阅读量，没有提供更多信息
解释性注释	用于解释复杂、精巧、敏感的代码块	通常因为代码含混不清才体现出这类注释的价值
标记性注释	提醒开发者某处的工作未做完
概述性注释	将若干代码行的意思以一两句话说出来	对于修改代码的其他人来说非常有用
目的性注释	用来指明一段代码的意图，而非解决的方法
代码无法表述的信息	包括版权声明、保密要求、版本号等

对于完工的代码，只允许有三种注释类型：代码无法表述的信息、目的性注释和概述性注释