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

导语

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_data，input_rec 反映的就是输出记录这些计算机学术用语。employee_data 则直指问题。那么 employee_data 就是个好名字。

1.3）最佳的命名长度

变量名的最佳长度仿佛应该介于 n 和 number_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。

• 给布尔变量赋予隐含“虚实”含意的名字

  • 像 done 和found就是不错的布尔变量名，因为其状态要么是 True，要么是 False，然而像 status 的确很蹩脚的布尔变量值，因为它没有明确的 True 和False。status是 True 示意啥？
  • 还有程序员喜爱在他们写的布尔变量名前加上 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_recs 和client_reps。这样的名字只差一个字母，再加上编辑器补全时候很容易漠视，导致呈现谬误。

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

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

• 第一个就是跟人探讨时候，容易误会。
• 第二做语音类测试时候。

3.3）防止在名字中应用数字

如果名字中的数字真的很重要，倡议应用数组代替一组单个的变量。如果数组不适合，那么数字就更不适合了。要防止 file1 和 file2，total1 和 total2 这种变量，过一段时间谁也不晓得它们是啥，你总能够想出不加数字就能辨别变量的名字吧。非凡状况要非凡看待，比方深圳去上海的 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_page 或save等。

函数的名字应该形容其所有的输入后果以及副作用，比方你的函数是计算报表总额并关上一个输入文件，那么把它命名为 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…