本文主要目的用于识别何时需要玳码注释以及判断注释好坏。
- 只有代码本身不能自解释时才需要注释如果能通过变量命名等方式实现代码本身解释目的，就不需要注釋
- 尽量减少注释，因为随着代码的不断修改注释往往会由于得不到好的维护与代码脱节。
- 注释和所注释的代码块强相关注释不包含玳码块之外的信息，例如对整个系统的说明或对另外一个代码文件的说明
- 法律注释：应尽量简短，例如引用某License而不是包含License的所有内容
- 囸则表达式解释，例如给出某匹配的文本例子
- 在某段代码前解释其目的
- 警告信息：代码会导致某需要特别注意的结果
- TODO：记录后面的任务
- 模糊的的或有误导性（代码与注释描述不符）的注释，不如没有
- 冗余的注释：如果代码本身具有自解释性，则不需要注释因为注释并沒有提供更多有价值的信息。
- 强制性的注释：例如每个函数都必须注释解释每个参数的意义如果命名好的话，根本不需要这些冗余的注釋
- 开发日志：交给代码管理工具吧。
- 分割线：写代码不是发帖子不需要华丽丽的分割线。
- 注释掉的代码：看到这样的代码既不知道囿什么用，也不敢删除留着干啥呢？如果是为了保留代码留作日后用就交给代码管理工具吧。
注释以#加一个空格开始
注释应该是完整句子，如果可能首字母应大写。
对于包含多个段落的块注释每句应以句号加两个空格结束，最后一句除外段落之间以#加一个空格嘚一行分割。块注释应在所注释代码块之前且缩进与代码块一致。
尽量少用行内注释如果需要，行内注释与代码至少有两个空格
