原文：How to make your code self-documenting?

译文：怎么让代码自我文档化？

译者：dwqs

在代码中找到一个放错地方并且没有用的注释是不是很有趣呢？

怎么样才能做到写很少的注释但仍能让代码易于理解呢？

一个主要的方式就是让代码自我文档化。当代码自我文档化的时候，就不需要注释去它的作用或者目的，并且也能使代码变得非常容易维护。

在这篇文章中，我将提供一些让你的代码自我文档化的方式。下面就是三种使得代码自文档化的基本方法：

• 命名：利用名字来解释变量、函数等的目的。
• 封装函数：将一些特定功能的代码封装成一个函数以明确目的。
• 引入变量：将表达式插入至专用变量。

这可能看上去很简单，但在实际操作过程中会让人觉得有点棘手。首先你得明白哪些地方有问题以及哪些地方适用这些方法。

此外，除了上述三种，还有一些应用比较广泛的方式：

• 类和模块接口：将类和模块中的函数暴露出来，让代码更加清晰。
• 代码分组：用组来区分不同的代码片段。

接下来我们将通过实例，具体讲一讲如何在实际应用中运用上述5个方法。

一、命名

  首先，看几个如何利用命名时代码变得清晰和自我文档化的例子。

  1、重命名函数

  给函数命名不是很难，你可以遵守以下规则：

• 避免使用含糊的字眼，例如“handle”或“manage”——handleLinks、manageObjects。
• 使用主动动词——cutGrass、sendFile，以表示函数主动执行。
• 指定返回值类型——getMagicBullet、READFILE。强类型的语言也可以用类型标识符来表明函数的返回值类型。

  2、重命名变量

• 指定单位——如果里面有数值参数，那可以加上其单位。例如，用widthPx来取代width以指定宽度的单位是像素。
• 不要使用快捷键——a和b都不能作为参数名。

二、函数封装

  接下来，看几个如何将代码封装成函数的例子。封装函数的一个好处就是避免代码重复，或者说改进代码结构。

  1、将代码封装成函数

  这是最基本的：将代码封装成函数以明确其目的。猜猜下面这行代码是干什么的：

var width = (value - 0.5) * 16;

  好像不是很清楚，当然有注释就一清二楚了，但是我们完全可以封装成函数以实现自文档化……

var width = emToPixels(value);
 
function emToPixels(ems) {
    return (ems - 0.5) * 16;
}

  唯一改变的是计算过程被转移到了一个函数里。该函数名明确地表达了它要做什么，这样一来就不必写注释了。而且，如果有需要后面还可以直接调用此函数，一举两得，减少了重复劳动。

  2、用函数代替条件表达式

  If语句如果包含多个运算对象，不写注释的话理解起来就比较难。

if(!el.offsetWidth || !el.offsetHeight) {
}

  知道上面这代码的目的不？

function isVisible(el) {
    return el.offsetWidth && el.offsetHeight;
}
 
if(!isVisible(el)) {
}

三、引入变量

  最后再讲讲如何引入变量。相较于上面两个方法，这个可能没那么有用，但是无论如何，知道比不知道好。

  1、用变量代替表达式

  看看上面的例子

if(!el.offsetWidth || !el.offsetHeight) {
}

  这下不封装成函数，用引入变量代替

var isVisible = el.offsetWidth && el.offsetHeight;
if(!isVisible) {
}

  2、用变量代替方程式

  我们也可以用来清楚说明复杂程式：

return a * b + (c / d);

  用变量来代替

var divisor = c / d;
var multiplier = a * b;
return multiplier + divisor;

四、类和模块接口

  类和模块的接口——也是面向公共的方法和属性——有点像说明如何使用的文档。

  看下面的例子：

class Box {
    public function setState(state) {
        this.state = state;
    }
 
    public function getState() {
        return this.state;
    }
}

  这个类也可以包含其他代码。我特意举这个例子是想说明公共接口如何自文档化。

  你能说出这个类是如何被调用的吗？很显然，这并不明显。

   这两个函数都应该换个合理的名字以表述它们的目的。但即便做到这一点，我们还是不怎么清楚如何使用。然后就需要阅读更多的代码或者翻阅文档。

   但是如果我们这样改一下呢……

class Box {
    public function open() {
        this.state = open;
    }
 
    public function close() {
        this.state = closed;
    }
 
    public function isOpen() {
        return this.state == open;
    }
}

  是不是清晰多了？注意：我们只是改动了公共接口，其内部表达与原先的this.state状态相同。

五、代码分组

  用组来区分不同的代码片段也是自文档化的一种形式。例如，像这篇文章中说的那样，我们应该尽可能将变量定义在靠近使用它的地方，并且尽可能将变量分门别类。这也可以用来指定不同代码组之间的关系，这样更加方便其他人知道他们还需要了解哪些代码组。

  看下面的例子：

var foo = 1;
 
blah()
xyz();
 
bar(foo);
baz(1337);
quux(foo);

var foo = 1;
bar(foo);
quux(foo);
 
blah()
xyz();
 
baz(1337);

六、其它建议

• 不要使用奇怪的标记，下面两个是等价的

imTricky && doMagic();

if(imTricky) {
    doMagic();
}

  显然后者比较好。语法技巧并没有带来什么好处。

• 命名常量：如果代码里面有一些特殊值，那最好给它们命名。var PURPOSE_OF_LIFE = 42;
• 制定规则：最好遵循相同的命名规则。这样阅读的人就能在参考其他代码的基础上正确猜测出各种事物的含义。

原文首发：http://www.ido321.com/1360.html

如何高效编写可维护代码？