什么是好的代码注释?

Use a comment when it is infeasible to make your code self­explanatory.
当你的代码不容易自我解释逻辑的时候,才需要写注释。

如果你发现自己的代码可以自我解释逻辑,则不需要添加注释。
例如下面代码中的注释都是没有意义的:

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

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

如果你发现自己的代码不容易自我解释逻辑,首先可以尝试修改代码,让它变得容易自我解释逻辑。

示例

例如下面这样一段计算最终价格的代码:

finalPrice = (numOfItems * itemPrice) - max(20, numOfItems) * 0.1;

其他人并不懂 max(20, numOfItems) * 0.1 是什么意思,因此你第一想法肯定是加上注释,例如:

// Subtract discount from price.
finalPrice = (numOfItems * itemPrice) - max(20, numOfItems) * 0.1;

其实更好的办法是引入一个可以自我解释的变量,例如:(这样其他人一眼也能看懂)

price = numOfItems * itemPrice;
discount = max(20, numOfItems) * 0.1;
finalPrice = price ­- discount;

示例

例如下面这样一段过滤字符串数组的代码:

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

其他人并不懂这一段的目的是什么,因此你第一想法肯定是加上注释,例如:

// Filter offensive words.
for (String word : words) { ... }

其实更好的办法是引入一个可以自我解释的方法名,例如:(这样其他人一眼也能看懂)

filterOffensiveWords(words);


String[] filterOffensiveWords(String[] words) {
  for (String word : words) { ... }
}

示例

使用更有意义的变量名,例如:
int width = ...; // Width in pixels.
我们可以使用 int widthInPixels = ...; 来取代注释。

...持续更新...

推荐阅读更多精彩内容

  • iOS编程规范0规范 0.1前言 为􏰀高产品代码质量,指导广大软件开发人员编写出简洁、可维护、可靠、可 测试、高效...
    iOS行者阅读 3,440评论 21 36
  • 推荐文章:禅与 Objective-C 编程艺 前言 为􏰀高产品代码质量,指导广大软件开发人员编写出简洁、可维护、...
    WolfTin阅读 615评论 0 0
  • 一. 为什么读这本书 很多同行在编写代码的时候往往只关注一些宏观上的主题:架构,设计模式,数据结构等等,却忽视了一...
    隐身人阅读 105评论 0 1
  • 缓存更新策略FIFO[First In First Out]。最先进入缓存的数据在缓存空间不足情况下最先清理出去L...
    Captain_tu阅读 15评论 0 0
  • 和修姐相识已有整整二十一年了。记得那是1997年的8月底,高考失利进了教育学院学前艺术系,而她刚好是去学校再进修...
    跳跳糖zhz阅读 25评论 0 1