自文档化的JavaScript代码的开发方法

551 查看

在我们的编程开发中，如果能在没有一行注释的代码中找到注释，是不是很意思呢？

我们经常容易犯一个错误：我们修改了一段代码，但是忘记修改更新注释。混乱的注释并不会打断你代码的执行，但是想象一下debug的时候会发生什么事情。你认真地阅读了注释，它说的是一件事，但是代码干的是另一件事。结果是，你浪费了很多时间发现注释是错误的，甚至最糟糕的是，你可能完全被误导了。

但是代码中完全不写注释也不是一个很好地选择。在我超过15年的编程经验中，我从未觉得代码库中的注释是完全没用的。

然而，有一些办法可以来帮助减少代码注释的必要性。我们可以利用某些编码技巧来让我们的代码变得更清晰，例如就是利用编程语言的特点。这样不仅能帮我们的代码变得更加清晰易理解，而且还能能帮助我们改善程序的设计。

这类代码通常被称为自文档化代码。让我来给大家展示下怎样利用这种方式编码。当然，我这里我演示的代码使用的是JavaScript语言，你们也可以利用这里大部分的技巧运用到其他的语言中。

概述

一些编程者将注释归纳到自文档化代码的范畴。在这篇文章中，我们只关注代码。注释很重要，但是却单独覆盖了太多东西。我们可以把自文档化代码归为三大类：

结构类自文档化。使用代码的结构和目录来让代码变得清晰
命名自文档化。例如函数或变量命名让代码更易理解
语句相关自文档化。我们利用语言的特性来让代码变得清晰

一、结构类自文档化

首先我们看下结构类自文档化。这里指的是通过移动部分代码来让代码变得清晰。

将代码移动到函数里面。

这和提取函数重构一样，意思是我们将已经写好的代码移动到一个新的函数里：即提取代码成为一个新函数。例如:

1	var width = (value - 0.5) * 16;

不是很清晰，这里添加一个注释会很有帮助，或者，我们将它提取到一个函数里面进行自文档描述：

var width = emToPixels(value);

function emToPixels(ems) {

return (ems - 0.5) * 16;

}

这里唯一的变化是我们把计算放到函数里面。函数的名称描述了代码的作用，所以代码的意思就不言而喻了。另一个好处是，我们现在有一个到处可以调用的辅助函数，所以这种方法也增强了代码复用性。

用函数代替条件表达式

如果没有注释，含有多个操作运算的语句很难理解。我们可以使用一个简单的方法来描述。

1 2	if(!el.offsetWidth \|\| !el.offsetHeight) { }

这段代码的目的是啥？

function isVisible(el) {

return el.offsetWidth && el.offsetHeight;

}

if(!isVisible(el)) {

}

同样，我们把代码移动到一个函数里面，代码就立即变得容易理解了。

使用变量代替表达式

使用变量代替表达式和将代码移入函数里面类似，但是相对于函数，我们是用一个变量。让我们再来看下这个语句：

1 2	if(!el.offsetWidth \|\| !el.offsetHeight) { }

这次我们用变量来代替表达式，而不是函数：

var isVisible = el.offsetWidth && el.offsetHeight;

if(!isVisible) {

}

这样比使用函数更好，例如，如果使用的逻辑非常明确，而且这段逻辑只在某一个地方使用一次，就适合用变量了。这种方法最常用的场景是在数学表达式中：

1	return a * b + (c / d);

我们可以这样让代码变得清晰:

var multiplier = a * b;

var divisor = c / d;

return multiplier + divisor;

因为我数学很差，想象一下上面的例子是一个有含义的运算，在任何场景下，你可以将复杂的表达式换成变量来给表达式代码添加本身的含义。

类和模块接口

接口不仅是类或模块的公用方法和属性，而且在使用中能起到自文档化的作用。来看下这个例子：

是不是很意思呢？