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

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



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



使用显示意图的名称



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



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



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



<?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一样。



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



做出有意义的区分



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



我们来看一下这个例子



<?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（或安装插件）来根据变量的使用范围给变量着色。



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



原文链接



https://medium.com/better-programming/how-to-create-meaningful-names-in-code-20d7476537d4



总结



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





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



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