Google代码健康：注释还是不注释

本文源于Google公司的马桶上的健康代码，作者：Chris Lewis & Bob Nystrom

在阅读代码时，通常没有什么比有适当的注释更有用的了。但是，有注释也并不总是好事。有时需要注释的原因可能表明应该开展代码重构活动。

如果无法使编写的代码不言自明，请使用注释。如果需要用注释来解释一段代码的作用，请首先尝试下面的方法：

反例：

// 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;

反例：

// Filter offensive words.

for (String word : words) { ... }

正例：

filterOffensiveWords(words);

反例：

int width = ...; // Width in pixels.

正例：

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...

另一方面，请避免仅重复代码的注释。这些只是噪音：

示例1：

// Get all users. 
userService.getAllUsers();

示例2：

// Check if the name is empty. 
if (name.isEmpty()) { ... }

注释还是不注释