好的评论解释的是“为什么”，而不是“是什么”，以及撰写好评论的另外 3 条规则

#1 你的评论应该解释为什么，而不是什么

#2 留下你的名字

3. 彻底

#4 避免混乱

评论……我知道……真是🔥的话题。希望服务器能处理好我们激动的心情……

不过玩笑归玩笑。如果你每天都要写代码，那么好的注释对于提高任何中大型代码库的效率都至关重要。唉，真是扫兴啊……

那么，让我们言归正传：注释并不是优秀代码库的附加部分，它们本身就是代码库的一部分。

这里有一些技巧可以帮助您写出更好的评论……

#1 你的评论应该解释为什么，而不是什么

“不需要注释。好的代码应该能够解释它的作用。”

如果您这样认为，那么您就误解了评论应该做什么。

注释不应该解释代码的作用。代码本身应该
解释它为什么存在，以及为什么以这种方式存在。

为什么与什么：

• 代码应该解释什么
• 评论应该解释为什么这段代码存在或者为什么它必须以不明显的方式做某事。

坏的：

class Newsletter
  # removes stuff from newsletter
  def remove(stuff)
  …
  end
end

好的：

class Newsletter
  # Note(andreasklinger): In case we run into XYZ we need to remove the user to avoid
  #   problems w/ ABC and DEFG's API. Read more here: https://.....
  def remove(stuff)
  …
  end
end

#2 留下你的名字

在Product Hunt，我们有一个习惯，就是在评论旁边留下名字。

例如：

Note(andreasklinger): This is a comment.

但您可以使用 git blame 来实现这一点。

人们会移动代码，人们会编辑你的代码行（比如有人会去掉代码末尾的空格？）。
一旦代码被移动或编辑得足够频繁，就没人会费心去找作者了。

特别是在较小的团队中，仅凭名称就可以帮助您理解某些事物存在的原因，或者是否应该尝试修复/改进它。

3. 彻底

“下一个开发商接管”几乎是一个神话。

通常“下一个开发人员”只是“快速路过”，她有自己的事情要做，而你的代码却妨碍了她。

想象一下，下一个人看到你的代码时，没有任何背景信息，而且只有非常有限的时间来更改它。

当你编写代码时，它对你来说很明显 - 但以后再也不会那么明显了 - 对任何人来说都不是，包括你自己。

• 解释时不要假设人们已经知道你的系统是如何运作的
• 解释你必须考虑的外部系统的特点
• 解释你必须考虑的内部系统怪癖
• 解释系统的哪些部分是遗留的
• 解释何时可以删除（例如遗留）代码（尽可能留下“X 完成后”或日期）
• 解释你需要做的黑客攻击以及它们为什么有效
• 解释不明确的内部相互依赖关系（例如依赖于结构或 API 的其他系统）
• 必要时可以写更长的段落
• 尽量避免使用外部文档。如果不在同一个文件中，人们就不会更新。
• 要求“留下一个 BFN”（留下一个大大的 f*** 注释）——也期望你的同事在需要时给任何代码留下注释

#4 避免混乱

Explicit > Implicit但是当明确变得多余时，您要避免明确。

写下你的评论。
写下评论后，再读一遍，看看哪些地方可以删除或简化。

如果你不能简单地解释它，那么你就没有足够理解它。

• 阿尔伯特·爱因斯坦

希望有帮助！

注释并非优秀代码库的附加内容，它本身就是代码库的一部分。
代码让机器更容易管理复杂的系统，而注释则让人类更容易管理。

hth，
欢迎随时在 Twitter 上联系我！

@andreasklinger