代码整洁之道在 JavaScript 中的应用——第四部分：注释

介绍

只评论那些具有业务逻辑复杂性的内容。

没有期刊评论

避免使用位置标记

结论

介绍

在这篇文章中，我们将描述开发人员在处理代码整洁问题时最常争论的话题之一。

许多开发者认为注释是一种好的做法，而另一些开发者则持完全相反的观点，认为使用注释是一种坏的做法。

很遗憾地告诉你，并没有绝对的规则，一切都取决于具体情况。事实上，在很多情况下，注释对软件开发毫无帮助，因为它们已经被其他工具取代，这些工具的功能比注释本身更强大。而在另一些情况下，注释可能会给我们正在开发或将来要阅读的源代码带来干扰。因此，在这些情况下，理想的做法是完全不添加注释。

另一方面，有些情况下注释是好的做法，例如在公共 API 的文档中，可以从中了解库的行为，但不能了解它的开发方式。

下一篇文章中，我将介绍几种注释会产生噪音、不应在代码中应用的做法，以便提高代码质量。

只评论那些具有业务逻辑复杂性的内容。

注释存在的唯一目的就是帮助程序员解释那些对他们来说难以理解的业务逻辑。注释绝不应该描述算法本身。我们应该认识到，好的代码通常都是自文档化的，因此，只要阅读源代码，就能理解其内容。注释是锦上添花，而非必不可少。

然而，算法中可能包含一些我们作为开发人员并不了解的特定业务逻辑。例如，信用卡操作、自有保险操作等等。以下示例展示了大多数代码中冗长且不必要的注释。不过，最后一条注释并非无关紧要，因为它涉及我们正在建模的问题领域内的操作，因此这条注释的存在并无坏处。这条注释描述的并非编程层面的操作，而是业务逻辑层面的操作。

function convert(data){
 // The result
 let result = 0;

 // length of string
 const length = data.length;

 // Loop through every character in data
 for (let i = 0; i < lenght; i++){
   // Get character code.
   const char = data.charCodeAt(i);
   // Make the hash
   result = (result << 5) - result + char;
   // Conver to 32-bit integer
   result &= result;
  }
}

等效代码如下，从这段代码可以看出，注释并没有增加价值，反而给代码带来了噪音。

function convert(data) {
  let result = 0;
  const length = data.length;

  for (let i = 0; i < length; i++){
    const char = data.charCodeAt(i);
    result = (result << 5) - result + char;
    result &= result; // Convert to 32-bit integer
  }
}

没有期刊评论

过去，评论就像日记一样，人们倾向于了解文件随着时间推移发生了哪些变化。我希望现在不再如此。在过去缺乏版本控制工具的情况下，这种做法或许情有可原。

如今，这项任务应该委托给版本控制软件（我推荐使用 Git）。因此，不再需要死代码、注释代码，尤其是不需要日志注释。

要获取此信息，您只需使用git log获取历史记录命令即可。

下面是一个带有期刊注释的代码及其更简洁的版本。

/**
 * 2018-12-20: Removed monads, didn't understand them (CC)
 * 2018-10-01: Improved using special mondas (JS)
 * 2018-02-03: Removed type-checking (LI)
 * 2017-03-14: Added add with type-checking (CC)
 */
 function add(a, b) {
   return a + b;
 }

 function add(a, b) {
   return a + b;
 }

避免使用位置标记

你应该避免使用位置标记，因为它们通常只会增加代码的冗余信息。
让函数名、变量名以及正确的缩进和格式来构建代码的视觉结构。

以下代码示例展示了带有位置标记的代码及其简洁版本。您应该意识到，这种使用注释的技术在开发者工具匮乏的年代已经过时。如今，在源代码中创建这些标记毫无必要，因为它们只会造成信息冗余。

///////////////////////////////
//  Controller Model Instantiation
///////////////////////////////
controller.model = {
  name: 'Felipe',
  age: 34
};

///////////////////////////////
//  Action Setup
///////////////////////////////
const actions = function() {
  // ...
};

controller.model = {
  name: 'Felipe',
  age: 34
};

const actions = function() {
  // ...
};

结论

评论是当今开发者之间争论最激烈的话题之一。许多开发者认为评论必不可少，而另一些开发者则持相反观点。在任何决策中，走极端都不是好事，软件开发也不例外。

因此，在这篇文章中，我尝试总结了三种通过添加注释来使代码变得糟糕的做法。然而，如果我们正在创建一个公共 API，那么添加注释可能很有意义，因为我们是在为 API 编写文档。

许多教师的一个不良做法是给生产代码的每一行都加上注释。这种不良做法源于早期教授初级程序员编写代码时的做法，当时教师会给每一行代码都加上注释，作为学习指南。

然而，拥有学习指南和在生产开发过程中对每一行代码进行注释之间有着巨大的差别。

最后，我们讨论的要点如下：

• 只评论那些具有业务逻辑复杂性的内容。
• 没有期刊评论
• 避免使用位置标记