在代码中找到一个放错地方并且没有用的注释是不是很有趣呢?
怎么样才能做到写很少的注释但仍能让代码易于理解呢?
一个主要的方式就是让代码自我文档化。当代码自我文档化的时候,就不需要注释去它的作用或者目的,并且也能使代码变得非常容易维护。
在这篇文章中,我将提供一些让你的代码自我文档化的方式。下面就是三种使得代码自文档化的基本方法:
这可能看上去很简单,但在实际操作过程中会让人觉得有点棘手。首先你得明白哪些地方有问题以及哪些地方适用这些方法。
此外,除了上述三种,还有一些应用比较广泛的方式:
接下来我们将通过实例,具体讲一讲如何在实际应用中运用上述5个方法。
首先,看几个如何利用命名时代码变得清晰和自我文档化的例子。
1、重命名函数
给函数命名不是很难,你可以遵守以下规则:
2、重命名变量
接下来,看几个如何将代码封装成函数的例子。封装函数的一个好处就是避免代码重复,或者说改进代码结构。
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);
将foo的所有使用组合放在一起,一眼望去就能知道各种关系。但是有时候我们不得不在中间调用一些其他函数。所以如果可以那就尽量使用代码分组,如果不可以,那就不要强求。
imTricky && doMagic();
if(imTricky) {
doMagic();
}
显然后者比较好。语法技巧并没有带来什么好处。