恰当使用注释

• 恰当的注释提升软件可理解性

• 代码走读时发现的问题，深入细节，解释通用知识，注释难以理解， 模板化注释，垃圾注释(username： uername)

• 注释不是越多越好

• 提升代码自身的表现力，而非依赖于注释

stop_flag： [False， False]
VS：
stop_test： False
create_log： False

• 太多的注释可能意味着代码自身的表现力差

• 注释要言简意赅，最好不要深入细节，细节变化太快，在一些年久失修的代码里很多注释牛头不对马嘴。

• 注释不要试图解释一些通用的知识，例如协议，这些通用知识应该通过其他方式来学。

• 加到代码里的任何东西(代码/changelog/注释)都有维护成本，注释也是。

• 注释(英文，即便是中文)的表现力不一定比代码强(伪代码)。

• 注释和文档一样是最低效的沟通方式，team 内部要即时沟通，面对面的沟通。

• 被全球使用的开源代码可能需要更多注释，自己公司内部使用的代码可以少一些。

• 很多注释终将成为代码里的垃圾，变成阅读代码的障碍(深入细节的，解释通用知识的，大段大段的注释，注释比代码还长)，太多的注释和太多的 log 让阅读代码变成了从垃圾堆里找有用的东西。

• 反对模板化的注释, 确实需要加的地方再加(某个参数/函数本身/返回值)

 // 文件头部注释
 /*
  * @Description:
  * @version:
  * @Company: BAT
  * @Author: OBKoro1
  * @Date: 2018-10-15 20:59:57
  * @LastEditors: OBKoro1
  * @LastEditTime: 2018-10-15 20:59:57
  */
 // 函数注释
 /**
  * @name:
  * @test: test font
  * @msg:
  * @param {type}
  * @return:
  */

• 使用 ide(vscode)折叠注释

• 垃圾注释

• 推荐的注释方式

slist = loginStr。split(。“) # strip off the hostname in login prompt

• 不推荐的注释方式

# strip off the hostname in login prompt
slist = loginStr。split(‘。“)

• 把要注释的一段代码抽成一个函数，并起一个合适的名字，哪怕名字很长