阅读 60

[译]到底要不要注释?

原文链接: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()) { ... }
关注下面的标签,发现更多相似文章
评论