阅读 319

【译】代码中如何写出更有意义的命名

作为一名开发人员,在编码过程中,你总会花很多时间来思考如何正确命名。因为名称无处不在,你需要考虑文件名、类名、方法名和变量名。

虽然我们需要花费很多时间,但是为了更好的命名还是值得的。本文我将向你介绍几个能够帮助你编写优质命名的简单规则。命名这件事本身也是一门艺术。

使用显示意图的名称

名称直接显示意图这件事说起来容易做起来难。你是否经常遇到一些难以判断其用途的名称?

一个好的经验法则是:如果一个名称需要注释,那么它本身就是不能说明意图的。

这个代码片段就演示了一个不能显示意图的变量命名。

<?php

private $s; // Time in seconds
复制代码

变量$s什么也说明不了。它没有任何时间流逝的感觉,我们最好是能选择一个名称指定测量内容和测量单位。下面这些变量名看起来就好很多。

<?php

private $days_since_creation;
private $elapsed_time_in_seconds;
private $seconds_since_last_modified;
复制代码

选择一个可以显示意图的名称能使一段代码更容易理解,从而降低维护成本。虽然选择的过程会花费一些时间,但这是为了节省更多的时间。我们来一起看看下面这个例子。

<?php

function getList() {
    $list1 = [];
    
    foreach ($this->the_list as $x) {
        if ($x % 2 != 0) {
            $list1[] = $x;
        }
    }
    
    return $list1;
}

function getOddNumbers() {
    $odd_numbers = [];
    
    foreach ($this->numbers as $number) {
        if (isOdd($number)) {
            $odd_numbers[] = $number;
        }
    }
    
    return $odd_numbers;
}
复制代码

你能马上说出 getList 函数的作用吗?恐怕需要看完具体实现之后才能说出来吧。而这段代码本身没有什么复杂的逻辑,一共3个变量和不到10行的逻辑。

接下来我们再来看看 getOddNumbers 这个函数,有没有发现,它的逻辑和 getList 其实是一样的。并且没有更加代码的复杂性,变量数量相同,代码嵌套层级也相同,唯一不同的是代码写的更加清晰了。但你却可以通过函数名一眼看出这个函数的作用。

通过上面的例子我们发现,只需要在命名上做一些小小的改变,就能够轻易的告诉别人你的代码的作用。

避免虚假信息

你应该避免留下一些能够掩盖代码真实意图的错误线索。

你应该避免使用一些有歧义的单词,例如不要把产品集合命名为 productList,除非它本身就是一个 List 类型的对象,这有可能会误导别人,更好的名字应该是 products

命名中千万不要使用大写的 o 或者小写的 L 因为它们看起来就像0和1一样。

对于相近的名称也要小心使用,例如,你让你来分辨 SomeMethodForEfficientHandlingOfFilesSomeMethodForEfficientStorageOfFiles 这两个单词时,你需要用多长时间,我相信大多数人第一眼看上去,就认为它俩完全一样。

做出有意义的区分

数字序列的命名不是命名的好方法,这样的名字是没有任何意义的,也不能够展示出作者的意图。

我们来看一下这个例子

<?php

public function duplicateArray($arr1, &$arr2) {
  foreach ($arr1 as $key => $value) {
    $arr2[$key] = $value;
  }
}
复制代码

这段代码中,如果我们用 $source#destination 来代替 $arr1$arr2 会更好。

使用你知道发音的名称

如果你们不知道名字的发音,那么你和人交流起来就会像白痴一样,这就很麻烦,毕竟社交是编程中比较重要的一个环节。你的命名最好是每个人都能够通过发音就马上就能想到的单词。

假如我们有一个变量命名为 $xsq 并且这在公司内是一个很重要的变量,想象一下你日常和同事的对话:

"Hey, what about that variable eke ess kjew?"

"You mean the access queue?"

有些开发者会尝试把变量凑成一个单词的发音,而有些开发者则会选择读单词的字母拼写。

使用便于搜索的名称

由一个字母组成的名称的不好之处在于难以定位。数字常量也有同样的问题,所以我们在开发过程中需要把魔数替换为常量。在代码里搜索数字8是一件很困难的事情,但是如果你搜索常量 MAX_BLOCKS_DISPLAYED 就会简单很多。单字母命名的唯一用例是在简短方法中的局部变量。

成员属性前缀

不要使用成员属性前缀。

有些开发者习惯把泪中所有的私有变量用下划线为前缀命名。不要这么做,你应该保证的是,你的类和方法要足够小,以至于你不需要使用这些前缀。

或者,你可以使用IDE(或安装插件)来根据变量的使用范围给变量着色。

把你的代码想象成一个露营地,让它尽可能的保持整洁。

原文链接

medium.com/better-prog…

总结

以上,就是创建有意义命名的一些原则和方法。有任何问题欢迎给我留言,本文灵感来源于《代码整洁之道》,推荐大家都读一下这本书。


原文结束了,我个人还是比较认可作者的观点的,代码中的各种命名还是要花时间去琢磨琢磨的,这里也分享一下我在工作中通过 code review 的一些小感悟吧。在代码中,文件名、类名、方法名,这些不要嫌长,要尽可能的达意,并且可读。而对于一些局部变量,则可以适当放宽限制,如果太长的话会导致代码中有很多不必要的换行,但是也最好不要出现 a1a2 这样的命名。因为这种是完全不能理解它代表什么的。

这篇文章在 medium 上收获的 3k+ 的 claps。所以就想着翻译过来推荐给大家,同时也推荐大家读一读《代码整洁之道》。