| 2021-03-07
要写注释，还是不用呢?
当阅读代码时， 没有什么比良好的注释内容更给力的了。
然而， 注释并不总是好事儿。
在哪些情况下，不应该写注释，而是应该重构
假如你的代码意图无法做到“不言自明”，再使用注释也不迟。
如果你认为需要用注释来解释一段代码在做什么，那么，还是先试一试下面的方法吧：
- 引入一个解释性的变量。
将下面这段代码
// Subtract discount from price.
finalPrice = (numItems * itemPrice)
- min(5, numItems)
* itemPrice * 0.1;
改写为
price = numItems * itemPrice;
discount = min(5, numItems) * itemPrice * 0.1;
finalPrice = price - discount;
- 抽取出一个新的方法（ methed ）。
例如，将下面的这段代码
// Filter offensive words.
for (String word : words) {
...
...
}
改写为：
filterOffensiveWords(words);
- 使用一个更有描述性的命名。
例如，将下面的这段代码
// Width in pixels.
int width = ...;
改写为：
int widthInPixels = ...;
- 万一你的代码有假设条件，就要增加一个检查点，而不是注释。
例如，
// Safe since height is always > 0.
return width / height;
改写为：
checkArgument(height > 0);
return width / height;
在哪些情况下，应该写注释
展示你的意图：解释为什么写这段代码，而不是它在做什么。
// Compute once because it’s expensive.保护未来那个善意的想修改你代码的人，以免它错误地“修复”了你的代码。
// Create a new Foo instance because Foo is not thread-safe.声明式:代码审查期间出现的问题或代码的读者可能有的问题。
// Note that order matters because…如果看起来你写了一段违反软件工程实践的糟糕代码，那就解释一下你的理由。
@SuppressWarnings("unchecked") // The cast is safe because…
避免注释仅仅是重复了代码已表达的内容。
因为这种做法是令人反感的，例如下面两段代码所示:
// Get all users.<br/>
userService.getAllUsers();
// Check if the name is empty.
if (name.isEmpty()) { ... }
发表时间：July 17, 2017
原文作者：Dori Reuveni and Kevin Bourrillion