乐趣区

关于前端:一文搞定代码中的命名

导语

Phil Karlton 已经说过:计算机科学畛域只有两件难事:缓存生效和命名。而命名又是写出整洁代码根底中的根底,本文的副标题其实是《对于命名的读书笔记》,本人在学习过程中的整理出来一点心得笔记,共勉!


为什么要做好命名?

任何一个傻瓜都能写出计算机能够了解的代码。唯有写出人类容易了解的代码,才是优良的程序员。—— Martin Fowler

整洁的代码如同柔美的散文。—— Grady Booch

程序写进去是给人看的,附带能在机器上运行。–《计算机程序的构造与解释》

读悬疑侦探类小说,透过神秘的文字揣测故事情节是个挺不错的体验。然而如果是在浏览代码,这种体验会让你泪奔。


做好命名很难

起名字这件事看似不难,然而要通过三思而行,取出货真价实、表白性好的名字并不是一件很容易的事。

命名为什么难呢?因为命名的过程自身就是一个形象和思考的过程,在工作中,当咱们不能给一个模块、一个对象、一个函数,甚至一个变量找到适合的名称的时候,往往阐明咱们对问题的了解还不够透彻,须要从新去开掘问题的实质,对问题域进行从新剖析和形象,有时还要调整设计和重构代码。因而,好的命名是咱们写出好代码的根底。

就像 Stack Overflow 的创始人 Joel Spolsky 所说的:“起一个好名字应该很难,因为一个好名字须要把要义稀释在一到两个词中。(Creating good names is hard, but it should be hard,because a great name captures essential meaning in just one or two words.)“

此外,Martin Fowler也示意过,他最喜爱的一句谚语,就是咱们的导语中提到的那句话:“在计算机科学中有两件难事:缓存生效和命名。(There are only two hard things in Computer Science:cache invalidation and naming things.)”


变量命名

1)好的命名的注意事项

1.1)命名要货真价实

这是为变量命名时最重要的思考选项。名字要齐全、精确的形容出该变量代表的事物。

最简略的办法是用文字描述变量所表白的含意,对变量的形容就是最好的变量名。这种名字很容易浏览,因为它不蕴含容易艰涩的缩写,同时也没有歧义。因为他对代表的事物做了残缺形容,因而不容易混同。

如形容运动场中座椅数数量,number_of_sets_in_the_stadium

备注: 本文命名都以 python 的命名形式书写,其余语言的依据语言命名格局转换即可。

如果有一种变量你没法形容,那么阐明你可能要从新思考业务,思考逻辑。

1.2)以问题为导向

好记的名字往往反映的通常都是问题,而不是解决方案。好的名字通常表白 what,而不是 how,如果名字反映了计算的某些方面而不是问题自身,那么它反映的就是 how 而不是 what

举例子阐明一个员工的数据记录,input_rec 或者 employee_datainput_rec 反映的就是输出记录这些计算机学术用语。employee_data 则直指问题。那么 employee_data 就是个好名字。

1.3)最佳的命名长度

变量名的最佳长度仿佛应该介于 nnumber_of_sets_in_the_stadium 之间。太短的名字无奈传播足够的信息。太长的名字很难写,同时还会使程序视觉构造变得模糊不清。

国外的大佬 Gorla、Benander 钻研发现,当变量名均匀在 10 到 16 个字符的时候,调试程序所破费的工夫最小,均匀名字长度在 8 到 20 个字符的时候也很适宜调试。这项准则并不是要求你肯定要把变量管制在 8 到 16 的长度。它强调的是如果你查看本人写的代码时发现很多更短的名字,你须要好好斟酌,确保这些名字是否足够清晰表白其含意。

太长: number_of_sets_in_the_stadium

太短: n,nsisd

正好: num_sets_in_stadium
1.4)变量名中的限定词

很多程序都有示意计算结果的变量:总额、平均值、最大值等等,如果要用相似 total、sum、average、max、min、record、string、pointer 这样的限定词来润饰某个事物,请把限定词放到名字的最初。

因为变量名中最重要的,即为这一变量赋予次要含意的局部该当位于最后面,这样这一部分就能够显得最为突出,又能够首先被浏览到。另外将限定词对立放在前面能够进步可读性,简化保护工作。

2)为特定类型的数据命名

2.1)为循环下标命名

循环咱们基本上天天用,小到写个 shell 脚本,大到登月工程,在软件工程中很常见。

既然常常那么 i、j、k 这些想来你也不生疏。如果一个变量要在循环之外用,那么就应该为它取一个比i、j 或者 k 更有意义的名字。

如果循环不是简略几行,浏览代码的人很容易就遗记原本的含意。

fruits = ['banana','apple','mango']
for fruit in fruits:
   print(f"以后水果:{fruit}")

为循环下标变量命名能够防止下标串话,就是想写 j 的时候写了 i,笔者自己之前写循环的时候就串话了,导致那个 bug 上了调试才定位找进去。

当然 i、j、k 这三个循环下标从 c 语言开始就随同着咱们,深入人心,所以想要用的时候尽量避免用于非下标状况,给人造成误会(想个更具备描述性的名字这事不就解决了)。

2.2)为状态变量命名

状态变量次要为了形容你的程序的状态。

倡议把标记也看作状态变量的一种,起一个比 flag、status 更好的名字,标记的名字不应该蕴含 flag,因为你看不出该标记是做什么的。为了分明起见咱们还应该用枚举类型、具名常量或者用作居民常量的全局变量来进行赋值。

2.3)为长期变量命名

长期变量用于存储计算的两头后果。

咱们常常把它们写成 temp、x 或者其余一些含糊且不足描述性的名字(有没有躺枪…)。

长期变量是一个信号,表明你还没有齐全把问题了解分明。而且,因为咱们将这些变量“正式”的赋予了一种“长期”状态,咱们就会往往更加随便的看待它,当你疏忽它,那么就有出错的可能了。

临时性的保留一些值经常是有必要的,然而的确不论从哪个角度看,你程序中的大多数变量都是长期的,把其中个别的称为临时性,阐明你还没有弄清楚它们的理论用处。

2.4)为布尔变量命名
  • 举荐一些经典的布尔变量名

    • done:
      用来示意某件事曾经实现。实现前 False,实现后为 True。
      error:
      用来示意有谬误产生。谬误产生前 False,产生时设置为 True。
      found:
      用来示意某个值曾经找到。没找到前 False,找到后为 True。
      success 或者 ok:
      用来示意某项操作是否胜利。操作失败 False,操作胜利为 True。
  • 给布尔变量赋予隐含“虚实”含意的名字

    • donefound就是不错的布尔变量名,因为其状态要么是 True,要么是 False,然而像 status 的确很蹩脚的布尔变量值,因为它没有明确的 TrueFalsestatusTrue 示意啥?
    • 还有程序员喜爱在他们写的布尔变量名前加上 is(有没有躺枪 -_-|)。加上了is 后,变量名就变成了 is_error?is_complete? 长处之一就是不会用于不隐含“虚实含意”的名字了,如 is_status,毛病就是升高可读性,比方if(is_found) 可读性略差于if(found)
  • 应用必定的布尔变量名

    • 比方 not_found,not_done 这样看起来就比拟难读了,来个语句你感受一下。
      if not not_found
      玩门萨测试呢?这样的名字就应该替换为 found 之类的。
2.5)为具名常量命名

因为具名常量很像变量,所以放在这里说一下。在为具名变量命名的时候,应该根据常量代表的含意命名,而不是该常量所代表的数值。

3)应该防止的名字

防止应用令人误会的名字或者缩写

要确保名字的含意是正确的,大家晓得 ATM 机是取钱的,然而网络中有 Asynchronous Transfer Mode(ATM)异步传输模式, 这种容易引起误会的尽量避免。

3.1)防止应用具备类似含意的名字

如果两个变量的名字替换而不影响你对程序的了解,那么你就须要为这两个变量从新改名字了,因为如果用在同一段代码外面很容易混同,呈现一下子不好发现的谬误。

防止应用具备不同含意但却有类似名字的变量

如果含意不同却名字类似的也要防止,比方 client_recsclient_reps。这样的名字只差一个字母,再加上编辑器补全时候很容易漠视,导致呈现谬误。

3.2)防止应用发音相近的名字

应用发音相近的词作为变量,次要有两个不适合点:

  • 第一个就是跟人探讨时候,容易误会。
  • 第二做语音类测试时候。
3.3)防止在名字中应用数字

如果名字中的数字真的很重要,倡议应用数组代替一组单个的变量。如果数组不适合,那么数字就更不适合了。要防止 file1file2total1total2 这种变量,过一段时间谁也不晓得它们是啥,你总能够想出不加数字就能辨别变量的名字吧。非凡状况要非凡看待,比方深圳去上海的 G205 国道,美国的51 区,倡议再创立一个含有数字名字之前,请确定没有更好的选项。

3.4)防止在名字中拼错单词

原本他人看你代码就要花点脑细胞,后果你拼错了。
content 和 context
highlite 和 hilite
大哥们,饶了看你代码的人吧。

3.5)防止仅靠大小写来辨别变量名

所以语言辨别大小写,但还是防止仅靠大小写辨别变量,大写名字和小写名字字面意思一样,还是不要做不同的变量了吧。

3.6)防止应用规范类型,变量和函数的名字

不要用语言的关键字。很多语言当初不能写关键字,然而大小写不辨别,比方 python 代码:

>>> if = 1
  File "", line 1
    if = 1
       ^
SyntaxError: invalid syntax
>>> If = 1
>>>

本文提供了这么多变量名的办法就不要用关键字这种了。

3.7)防止应用与变量含意齐全无关的名字

就问你怕不怕?还有的喜爱给变量起一些对本人非凡意义的名字作为变量名,除非程序真的跟你非凡意义无关。这些能防止防止吧。

3.8)防止在名字中蕴含容易混同的字符

把下列不属于该组的名字圈进去:

eye_Chart1 ttl5 TTLCONFUSION

eye_ChartI ttlS TTLCONFUSION

eye_Chart1 tt1S TTLC0NFUSION

还是不要搞这些找不同游戏能力呈现的变量哈。


函数命名

1. 形容函数所做的所有事件

函数的命名应该是动词或者动词短语,如 delete_pagesave等。

函数的名字应该形容其所有的输入后果以及副作用,比方你的函数是计算报表总额并关上一个输入文件,那么把它命名为 computer_report_totals() 不能算残缺。残缺的应该是 computer_report_totals_and_open_output_file()

如果写一些带有副作用的子程序,那么就会起出下面那种长出天际的名字,解决这个问题的方法不是应用描述性较弱的 computer_report_totals() 命名形式,而是换一种编写形式,间接了当地写成解决问题,不产生副作用。

2. 给函数命名时要对返回值有所形容

函数有返回值,因而,函数的命名要应该针对其返回值进行。比如说 xxx_is_ready 这样的,一看就让人晓得是返回的布尔值。

3. 精确应用对仗词

命名时恪守对仗词的命名规定有助于放弃一致性,从而进步可读性。像 first/last,这样的对仗词就很容易了解,而像 file_open()l_close() 就很让人蛊惑了,上面列出一些常见的对仗词组。

add/remove
increment/decrement
open/close
begin/end
insert/delete
show/hide
create/destroy
lock/unlock
source/target
first/last
min/max
start/stop
get/put
next/previous
up/down
get/set
old/new
4. 函数名字长度

钻研表明,变量名的最佳长度是 9 到 15 个字符,在面向对象的语言中,函数是跟在对象的名字之后,这实际上是为其提供了一部分的名字。重点的尽可能的含意清晰,长短要视名字是否清晰而定。

5. 为罕用操作确立命名规定

在某些零碎里,辨别不同类别十分重要,而命名规定往往能是批示这种区别的最简略也是最牢靠的方法。漠视了为返回对象标识的类函数建设一个命名规定,看看上面的名字

  • employee.id.get()
  • dependent.get_id()
  • candidate.get_id()
6. 类命名

类的命名应该是名词或者名词短语,如 Customer 或者 AddressParser


命名工具举荐

Codelf 由前网易前端工程师出名挪动前端调试工具 MIHTool 的作者基于 searchcode 和有道词典开发实现。目前开源在 Github 上。

Codelf:http://unbug.github.io/codelf/
Codelf 的 github repo:https://github.com/unbug/codelf

文学系的能够搜搜热词:盘它

我太南了


总结

白居易每作一首诗,都要给不识字的老太太念念,老太太能听懂的,就要,听不大懂的,就改。咱们的代码命名是咱们写成好代码的根底,也应该奔着这个指标走。大家看文章过程中感觉有不妥的或者不适合的中央,欢送探讨交换哈。


参考书籍

《代码大全 2》:https://book.douban.com/subje…
《代码整洁之道》:https://book.douban.com/subje…
《重构》:https://book.douban.com/subje…

转自:于颜川 KM 分享

更多后盾和前端开发标准

蓝鲸文档核心开发指南:https://bk.tencent.com/docs/d…

Python 代码标准小结:https://bk.tencent.com/s-mart…


蓝鲸智云

本文由腾讯蓝鲸智云编辑公布,腾讯蓝鲸智云(简称蓝鲸)软件体系是一套基于 PaaS 的技术解决方案,致力于打造行业当先的一站式自动化运维平台。目前曾经推出社区版、企业版,欢送体验。

  • 官网:https://bk.tencent.com/
  • 下载链接:https://bk.tencent.com/download/
  • 社区:https://bk.tencent.com/s-mart…
退出移动版