喜欢代码而不是注释-CFANZ编程社区

我想我们都同意代码注释是记录难以遵循的代码的好方法。有时没有办法让代码像你想要的那样清晰，而注释是一个很好的解决方案。

也就是说，评论有一个大问题：它们可能会过时。不正确的过时注释可能会导致您浪费大量时间进行调试。您可能会出于保持代码和注释同步的最佳意图而着手，但实际上随着时间的推移它不会发生。

如果可以使代码更明确，最好尽可能删除注释。我最近遇到了一个很好的例子，它显示了这一点。

评论在行动中的问题

我正在使用一个 API，它会code在每个响应上使用自定义属性进行响应。此 API 正在接受查询并返回搜索结果，code响应中的将表示响应是否成功、未找到任何结果或是否存在 API 错误。我在一个小的 JavaScript 模块上编写了第一个 pass 来包装这个 API，最后得到的代码看起来像这样：

makeRequestToLibrary().then(({ code }) => {
  if (code === 2000) {
    // 2000 is the success code
    return { success: true, ... }
  } else if (code === 4040) {
    // 4040 = our request returned no results
    return { success: false ... }
  } else if (code === 4020 || code === 4021) {
    // 4020 and 4021 are API issues - invalid key, invalid request, etc
    return { success: false, ... }
  }
})

这很好用，而且相当清楚，但它对过时的评论问题敞开了大门。开发人员可以很容易地添加我们需要处理的新代码，而不是更新评论，或更改代码的 API，或两者的组合。你可能会遇到这样的事情：

} else if (code === 4030) {
  // 4020 and 4021 are API issues - invalid key, invalid request, etc
  return { success: false, ... }
}

这里的注释与错误无关 - 是4030新的错误代码的情况，还是我们应该处理的情况4020而不是4030我们用数字打错了？这是不可能的。

删除代码注释

我们可以编码将状态代码映射到响应的知识，而不是注释，这样代码就可以自我记录，我们可以删除注释，同时保持我们的目标清晰。

为此，我们可以创建一个将响应类型映射到代码的对象：

const API_RESPONSES = {
  SUCCESS: 2000,
  NO_RESULTS: 4040,
  INVALID_KEY: 4020,
  INVALID_REQUEST: 4021,
}

现在更新我们的代码（现在我已经保留了评论）：

makeRequestToLibrary().then(({ code }) => {
  if (code === API_RESPONSES.SUCCESS) {
    // 2000 is the success code
    return { success: true, ... }
  } else if (code === API_RESPONSES.NO_RESULTS) {
    // 4040 = our request returned no results
    return { success: false ... }
  } else if (code === API_RESPONSES.INVALID_KEY || code === API_RESPONSES.INVALID_REQUEST) {
    // 4020 and 4021 are API issues - invalid key, invalid request, etc
    return { success: false, ... }
  }
})

请注意，现在我们的注释如何有效地复制代码告诉读者的内容。任何想了解映射到每种响应类型的代码的人只需要跳转到定义API_RESPONSES并找到它。我们可以删除评论而不会失去任何清晰度：

makeRequestToLibrary().then(({ code }) => {
  if (code === API_RESPONSES.SUCCESS) {
    return { success: true, ... }
  } else if (code === API_RESPONSES.NO_RESULTS) {
    return { success: false ... }
  } else if (code === API_RESPONSES.INVALID_KEY || code === API_RESPONSES.INVALID_REQUEST) {
    return { success: false, ... }
  }
})