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

21

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

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

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

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

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

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

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

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

接下来我们将通过实例,具体讲一讲如何在实际应用中运用上述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);

将foo的所有使用组合放在一起,一眼望去就能知道各种关系。但是有时候我们不得不在中间调用一些其他函数。所以如果可以那就尽量使用代码分组,如果不可以,那就不要强求。

六、其它建议

  • 不要使用奇怪的标记,下面两个是等价的
imTricky && doMagic();
if(imTricky) {
    doMagic();
}

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

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

来源:http://www.ido321.com/1360.html

声明:本站所有文章,如无特殊说明或标注,均为本站原创发布。任何个人或组织,在未征得本站同意时,禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益,可联系我们进行处理。
  1. 免费下载或者VIP会员资源能否直接商用?
    本站所有资源版权均属于原作者所有,这里所提供资源均只能用于参考学习用,请勿直接商用。若由于商用引起版权纠纷,一切责任均由使用者承担。更多说明请参考 VIP介绍。
  2. 提示下载完但解压或打开不了?
    最常见的情况是下载不完整: 可对比下载完压缩包的与网盘上的容量,若小于网盘提示的容量则是这个原因。这是浏览器下载的bug,建议用百度网盘软件或迅雷下载。 若排除这种情况,可在对应资源底部留言,或联络我们。
  3. 找不到素材资源介绍文章里的示例图片?
    对于会员专享、整站源码、程序插件、网站模板、网页模版等类型的素材,文章内用于介绍的图片通常并不包含在对应可供下载素材包内。这些相关商业图片需另外购买,且本站不负责(也没有办法)找到出处。 同样地一些字体文件也是这种情况,但部分素材会在素材包内有一份字体下载链接清单。
  4. 付款后无法显示下载地址或者无法查看内容?
    如果您已经成功付款但是网站没有弹出成功提示,请联系站长提供付款信息为您处理
  5. 购买该资源后,可以退款吗?
    源码素材属于虚拟商品,具有可复制性,可传播性,一旦授予,不接受任何形式的退款、换货要求。请您在购买获取之前确认好 是您所需要的资源

评论(0)

提示:请文明发言