[译]到底要不要注释？一个持续更新的github笔记，链接地址：Front-End-Basics，有空来玩。读代码时，

原文链接：https://testing.googleblog.com/2017/07/code-health-to-comment-or-not-to-comment.html

一个持续更新的github笔记，链接地址：Front-End-Basics，有空来玩。

读代码时，一个适当的注释往往很有用。不过，也不能随意的瞎注释。而且有时候这段代码需要注释，往往意味着代码应该被重构了。

当你的代码不能不言自明时，要加注释。如果你觉得要加一个注释来说明这段代码是干了点啥，不如先试试下面的几种方法：

介绍一个变量

// 从价格中减去折扣
finalPrice = (numItems * itemPrice)
    - min(5, numItems) * itemPrice * 0.1;

price = numItems * itemPrice;
discount =
    min(5, numItems) * itemPrice * 0.1;
finalPrice = price - discount;

抽出一个方法

// 过滤敏感词
for (String word : words) { ... }

filterOffensiveWords(words);

用一个更具有描述性的标识名称

int width = ...; // 宽度以像素为单位

int widthInPixels = ...;

给你存在假设的代码添加一个检查

// height > 0 时是安全的
return width / height;

checkArgument(height > 0);
return width / height;

下面也列举了一些恰当有用的注释：

表明你的用意：解释为什么代码要这么写（而不是它干了什么）

// 因为很耗费性能，所以只计算一次

防止之后好心的维护者对你的代码进行错误的“修复”

// 因为 Foo 不是线程安全的，所以要创建一个新的 Foo 实例

说明：code review 的时候发现的问题或者看代码的人碰到的问题

// Note：订单很重要，因为...

解释一下那些看上去不太好的软件工程实践的理由

@SuppressWarnings("unchecked") // 这个列表是安全的，因为...

换句话说，要避免那些仅仅是重复说明代码干了点啥的注释。这样的注释没啥用，看着还烦。

// 获取所有的用户
userService.getAllUsers();

// 如果 name 为空时的检查
if (name.isEmpty()) { ... }