Clean Code之路——注释

本文主要目的用于识别何时需要代码注释，以及判断注释好坏。

代码注释原则

1. 只有代码本身不能自解释时才需要注释，如果能通过变量命名等方式实现代码本身解释目的，就不需要注释。
2. 尽量减少注释，因为随着代码的不断修改，注释往往会由于得不到好的维护与代码脱节。
3. 注释和所注释的代码块强相关，注释不包含代码块之外的信息，例如对整个系统的说明或对另外一个代码文件的说明。

需要注释（好注释）

1. 法律注释：应尽量简短，例如引用某License而不是包含License的所有内容。

# Copyright (C) 2018 by XXX, Inc. All rights reserved.
# Rleased under ther terms of GNU General Public License version 2 or later

2. 正则表达式解释，例如给出某匹配的文本例子。

# format matched kk:mm:ss

3. 在某段代码前解释其目的

# Compute logistic value
code blocks

4. 警告信息：代码会导致某需要特别注意的结果

# Don't run unless you have accessed the Internet
code blocks

5. TODO：记录后面的任务

无需注释（坏注释）

1. 模糊的的或有误导性（代码与注释描述不符）的注释，不如没有。
2. 冗余的注释：如果代码本身具有自解释性，则不需要注释，因为注释并没有提供更多有价值的信息。
3. 强制性的注释：例如每个函数都必须注释解释每个参数的意义，如果命名好的话，根本不需要这些冗余的注释。
4. 开发日志：交给代码管理工具吧。
5. 分割线：写代码不是发帖子，不需要华丽丽的分割线。
6. 注释掉的代码：看到这样的代码，既不知道有什么用，也不敢删除，留着干啥呢？如果是为了保留代码留作日后用，就交给代码管理工具吧。
7. 以Python为例的docstrings：如果不是public的 modules, functions, classes, and methods不需要docstrings。

PEP8 注释规范

注释以#加一个空格开始。
注释应该是完整句子，如果可能，首字母应大写。
对于包含多个段落的块注释，每句应以句号加两个空格结束，最后一句除外，段落之间以#加一个空格的一行分割。块注释应在所注释代码块之前，且缩进与代码块一致。
尽量少用行内注释，如果需要，行内注释与代码至少有两个空格。

参考资料

[1] Clean Code
[2] PEP8： https://www.python.org/dev/peps/pep-0008/#comments