技术
技术

代码的艺术-命名

在编写代码过程中,无论是变量,类还是函数等等,一个清晰可以理解的名字,是至关重要的,能够让别人更加清晰的了解你的思路以及代码的含义。

可以说,每一个命名,都是一个简短的注释。

一、选择具有清晰表达含义的命名

日常编码中,我们经常用到get, size等进行命名,但实际上其并没有准确的表达出需要表达的信息,别人能够从中获取到的信息很少。

比如说get,get到了什么,从哪里get, 缓存还是数据库,或者从接口获取等等,这些信息都没有清晰的表达出来。举例来说,如果我们用这样的名字,如getUserNameFromCache,是不是更加的清晰了呢?

下面同样举了一些常见的命名词汇,准确的运用这些词汇,能够让你在命名时,更好的表达自己的代码逻辑和作用。

代码的艺术-常用词汇

二、避免使用空洞的名字

何为空洞的名字?这里指的就是tmp, retval, foo这类名字。

以tmp举例来说,如果变量的唯一目的就是临时存储,如:

tmp := right
right = left
left = tmp

这时用tmp就很好,因为它的作用就仅仅只是临时存储,且生命周期只是几行代码之间。

但如果不是这种场景,仅仅只是因为懒惰就是用类似tmp之类的名字,就有些不合时宜了。

即便有些场景,确实是临时存储的含义,但最好也要更加明确些信息,如: tmpFile, tmpCache等等,不要只是单纯的tmp了事。

同时,常用的另外一种情况就是循环迭代的时候,我们常用的都是i, j, k,或者 k, v, key, val, 如果可以的话,换成具体表达含义的词汇会更好,如:

for userID, userName := range userMap {
    ...
}

三、命名中尽可能附带更多的信息

如果关于一个变量,有什么更重要的事情必须让读者知道,那么将额外的词加入到命名中就是一个非常好的做法。

如我们最常见的场景,数据库中有很多的数据表,很多的表里面都有一个字增ID字段,如果我们将这个字段都命名为 id , 那么在代码中,就会出现大量的 id 字段名,而且我们并不能直观的知道每一个 id 字段究竟是属于哪张表,这无疑会对我们的开发造成一些困扰,甚至可能会造成一些非常隐蔽的bug。

但是如果我们在命名该字段时,附加上表的信息,如用户表,则为user_id, 角色表则为 role_id, 这样无疑会更加的清晰,也让代码更具可读性。

再举一个常用例子,附加变量的类型。

如果一个变量 user_id 是一个十六进制字符串的话,可以这样命名 user_hex_id, 这样就能够让读者很清晰的就知道这个变量的格式时十六进制的字符串。

类似的还有很多,如: plaintext_password(明文密码), unescaped_comment(未转义的用户评论), html_utf8(已转化为utf8格式的html字节), data_urlenc(以url方式编码的数据)等等。

四、名称不能过长

按照以上的讨论,命名时,我们需要尽量附带更多更明确的信息,但这样势必会增加命名的长度,而太长的命名实际上是非常不友好的,这其中就涉及到了一个取舍的问题。

在取舍的过程中,有几点可供参考下:

1. 如果该命名的生命周期极短,最多就几行代码间会使用,可以适当的使用短些的名字,因为此时上下文语境还是很清晰的,不会造成太大的困扰。

2. 慎用缩略词和缩写,基本原则为,其他人看到这个名字是否能够理解该缩略词的含义。

3. 尽可能丢掉无用的词,如ConvToString() => ToString(),  所表达的含义完全一致,但很明显ToString更简短些。

五、不要使用会造成误解与歧义的名字

英文中,很多词汇本身是有歧义的,比如说limit, 相信大家经常看到这样的命名,name_too_long_limit,但这样的命名实际是有歧义的。如name_too_long_limit = 5,我们并不能明确其临界值 5 是否在允许范围之内,而如果用max_chars_in_name, 则明显更加明确,同时也携带了长度是以char计算的信息。

在比如,如果要表示一段数值范围,start 和 stop也是常用的命名,但相较而言,无疑first, last这种明显包含临界值的词汇,更加不会造成困扰。

另外值得一提的就是,给布尔值命名时,最好避免使用反义词命名,如:has_not_used, is_not_allowed 等等,而是尽量使用 has_used, is_allowed这种,这样更加的简单易理解。

六、考虑具体应用场景

命名的方法是多方面考虑的,也不是能够以偏概全的,涉及到具体应用场景还需要具体的考虑。

比方说,如果你写了一个函数,GetUserNameFromCache(), 粗看上去没什么问题,但如果你这个函数里面,走了大量的复杂逻辑,设置调用的第三方接口等等的话,就极易可能会对调用者造成困扰。

毕竟对调用者来说,FromCache,第一想法就是认为这个函数是一个很快捷,直接读缓存,耗时非常短的函数,你不可能要求所有调用你函数的人都去先看下你函数的实现,如果该函数被大批量错误使用的话,极有可能造成很大的隐患。

总结

  1. 选择具有清晰表达含义的命名
  2. 避免使用空洞的名字
  3. 命名中尽可能附带更多的信息
  4. 名称不能过长
  5. 不要使用会造成误解与歧义的名字
  6. 考虑具体应用场景

精品课程


guest

0 评论
内联反馈
查看所有评论