洗涤您的代码：避免评论
#javascript #编程 #cleancode

您阅读了我即将出版的《干净代码》一书的摘录，“清洗您的代码：写一次，阅读七次。

有些开发人员从不评论他们的代码，有些评论太多了。前者认为该代码应该是自我记录的，后者在某个地方读到他们应该始终评论其代码的地方。

两个都是错误的。

我不相信自我记录的代码。是的，我们应该重写不清楚的代码以使其更加明显，并使用有意义和正确的名称，但是只有代码可以通过代码进行尝试。

评论太多的是没有帮助的：评论开始重复代码，而不是帮助理解它，而是引入了噪音和重复。

摆脱评论（或没有）

有一种避免评论的流行技术：当我们想在评论中解释一块代码时，我们应该将此代码移至其自己的功能。

在已经很长的代码中提取复杂的计算和条件通常是一个好主意：

if (
  platform.toUpperCase().indexOf('MAC') > -1 &&
  browser.toUpperCase().indexOf('IE') > 1 &&
  this.wasInitialized() &&
  this.resize > 0
) {
  return true;
}

在这里，我们可以将条件提取到具有有意义名称的自身功能或变量中：

const isMacOs = platform.toUpperCase().includes('MAC');
const isIE = browser.toUpperCase().includes('IE');
const wasResized = this.resize > 0;
if (isMacOs && isIE && this.wasInitialized() && wasResized) {
  return true;
}

现在，条件更短且更可读，因为名称可以帮助我们了解该条件在代码上下文中的作用。

但是，我不认为将线性算法（甚至是长的算法）分为几个函数，然后将它们称为一个函数，使代码更可读。在函数之间跳跃（甚至更大的文件）比滚动要难，如果我们必须研究函数实现以了解代码，那么抽象就不是正确的。当所有提取功能都是同一算法的一部分时，命名也可能是一个问题。

总的来说，当代码通过其物理指标（如线数）测量时，我不喜欢。长功能总是很难读取和修改，而真正复杂的代码可能很小。我们讨论了代码在鸿沟和征服中更详细的分裂，或合并和放松章节。

好评论

评论对于回答为什么以某种（通常是神秘的）方式编写：

  • 如果代码正在修复错误或是第三方库中错误的解决方法，则票证号或链接将很有用。
  • 如果有一个明显的简单替代解决方案，则评论应解释为什么在这种情况下该解决方案不起作用。
  • 如果不同的平台的行为不同，并且代码对此进行了说明，则应在评论中提及。

这样的评论将使我们免于意外重构，这使代码更容易，但会删除某些必要的功能或为某些用户打破它。

高级评论（解释代码的工作原理）也很有用。如果代码实现算法，请在其他地方解释，则该位置的链接将很有用。

，任何黑客都应在HACK或FIXME中解释：

  // HACK: Importing defaultProps from another module crashes Storybook Docs,
  // so we have to duplicate them here
  static defaultProps = {
    label: '',
  }

TODO评论还可以（更像 okeish ），如果他们在完成某件事时包含票证号。否则，它们只是梦想，可能永远不会实现。除非一个梦想 正是我们要记录的：该代码所做的渴望比进行错误处理，特殊情况，支持更多平台，次要功能等要多 - 但这可能是由于缺乏时间而实施的。

// TODO: On React Native it always returns DEV, since there's no actual location available
const getEnvironment = (hostname = window.location.hostname) => {
  if (hostname.includes('qa.')) {
    return Environment.QA;
  }
  if (hostname.includes('example.com')) {
    return Environment.PROD;
  }
  return Environment.DEV;
};

想法：也许我们应该开始使用DREAM评论。

不好的评论

我们谈论了有用的评论。但是，还有更多我们永远不应该写的评论。

可能的评论可能是评论 代码的工作原理。他们要么用更详细的语言重复代码，要么解释语言功能：

// Fade timeout = 2 seconds
const FADE_TIMEOUT_MS = 2000;

// This will make sure that your code runs
// in the strict mode in the browser
'use strict';

代码评论不是教队友如何使用某些语言功能的最佳场所。代码评论，配对编程会议和团队文档将更合适，有效。

接下来，伪造评论：他们假装解释了一些决定，但实际上他们没有解释任何事情，而是指责别人的代码和技术债务不佳：

// force 24 hours formatting for Chinese and Korean
const hour12 = locale === 'zh' || locale === 'ko' ? false : undefined;

我在一次性设计“调整”中看到了很多这些评论。例如，评论会说有使用非标准颜色的设计要求，但它不会解释为什么需要它，为什么在这种情况下没有任何标准颜色可以使用： 

.shareButton {
  color: #bada55; // Using non-standard color to match design
}

，我的意思是真的 laste ：

// Design decision

// This is for biz requirements

// Non-standard background color needed for design

// Designer's choice

// Using non-standard color to match design

要求是一个非常棘手的词。通常，被视为要求的是，开发人员，设计师和项目经理之间缺乏教育和协作。如果我们不知道为什么需要某件事，我们应该始终问，答案可能会令人震惊！

可能根本没有要求，我们可以使用项目主题中的标准颜色：

.shareButton {
  color: $text-color--link;
}

或可能有真正的理由使用非标准颜色，我们可能会发表评论：

$color--facebook: #3b5998; // Facebook brand color
.shareButton {
  color: $color--facebook;
}

无论如何，我们有责任问为什么在必要时多次。

与解释条件的评论相同：可能不需要特殊情况，我们可以通过其评论删除整个条件。在Avoid conditons章中查看更多内容。

开始思考：

  • 用有意义的函数替换评论。
  • 删除评论，即添加了代码中尚未添加的任何内容。
  • 询问为什么首先存在记录要求或决定。

如果您有任何反馈，tweet me，github上的open an issue或通过artem@sapegin.ru给我发电子邮件。 Preorder the book on Leanpub或read a draft online。