写点什么

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

用户头像
Jackey
关注
发布于: 2020 年 08 月 06 日
【译】代码中如何写出更有意义的命名

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



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



使用显示意图的名称



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



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



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



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



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



原文链接



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



总结



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






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



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



发布于: 2020 年 08 月 06 日阅读数: 105
用户头像

Jackey

关注

什么都知道一点的程序员 2018.03.09 加入

还未添加个人简介

评论

发布
暂无评论
【译】代码中如何写出更有意义的命名