前端规范与思考(一)———命名规范

本文属于原创文章,转载请注明–来自桃源小盼的博客

前言

其实这并不是第一次制定这个规范了,但这次我想制定一个有具备集大师之所长,还接地气的前端命名规范,希望是得到他人的认可,还能触动一些人去写出更优秀的代码。

所以,我尽力找到了所有和命名规范有关的书和资料(参考资料部分)。前前后后读了半个月吧,很多内容都不是第一次看了。这些书的每个章节,我都挺认同的,但我还是一团乱麻,不知道怎么去制定这个规范。

所有人都在告诉我,有意义的命名有意义的命名有意义的命名,重要的事情说说三遍,那就继续说下去。

《代码整洁之道》第二章的标题就是有意义的命名。它说得对,就像上学时语文课,如果文章是充斥着之乎者也的古文,总觉得不太懂。而如果是优美的散文,感觉看懂了,但经常反问自己,我真的懂了吗?不过豹子头林冲风雪山神庙我看懂了。一个好的故事,总是能让我们很快明白和共情。但代码它不是故事,它是说明文、是用户手册。

通常我们一直在说开发软件,开发产品,而其实我们是开发新功能和维护升级旧功能。如果我们看不懂它,又谈何维护升级呢?那么有意义的命名和清晰的结构,对程序员来说,就是一本用户友好的说明书,就是维护升级手册。

名字是阅读和理解代码的基础,所以只要能具体地指导我们命名,就是一个命名规范了。我给这个最小可行性命名规范,总结了三点原则:

  • 确切的命名规则
  • 同一场景下一致的命名
  • 如何避免糟糕的命名

遵守这个规范,并不能保证起个好名字,需要不断地学习提高,阅读开源代码,读一些好书,团队代码审查,这些事情都能帮我们提高起个好名字的能力。

如何起名字

我查看的这些资料,几乎都是外国人写的,我们有一个他们没有提到的缺陷,英语查,英文不是我们的母语。虽然我们从中小学就开始学习英语,但是日常生活里使用的很少,所以对英语还是疏远,对单词在不同语境下的含义,理解就更差了。

所以我们真正要做的是,起一个好的英文名字,所以这件事是有难度的,所以要不断地学习单词、阅读英文文章和在工作中实践。不过坚持是我们能做到的事情,也是一个优秀的人,必须做到的事情。

1.命名使用准确含义(通常是业务上)的单词

data、info、flag、process、handle、manage、modify这些词汇的范围都太宽泛了,几乎适合每个业务,并不能让我们理解业务的逻辑。

1
2
3
4
5
6
7
8
9
// bad
getInfo
handleChapter
flag

// good
getBooks
approveChapter
isNumber

2.最能表达业务含义的单词前置

为什么要前置呢?我们习惯的阅读方式是从左往右,人通常对映入眼帘的第一个东西印象深刻。

1
2
3
4
5
// bad
totalUser

// good
userTotal

3.禁止自己创造缩写,可以使用常见的缩写(行业或团队内广泛使用)

我看到太多人在创建缩写,不仅变量的缩写,还有很多产品名的缩写。如果你很了解这些缩写,那么不会对你造成困扰,但如今的工作情况是,公司人员流动频繁,跨团队合作很多,当你参加一个会议,其他人的话语中夹杂着各种缩写,“我们刚在bpm里加上了qx”,试用你能明白他们在聊什么吗?

马斯克曾在2010年5月,给全公司发送了主题为“首字母缩写词真恶心”的邮件,在这封邮件里他语气粗暴地说:除非得到我的批准,其他缩写词不能列入SpaceX的词汇表。

4.禁止使用拼音,除非是项目或产品名

5.不要拼错单词

现代的编辑器,如果单词拼错,一般都有智能的波浪线提醒,然而很多人还是视而不见。如果英语能力提高了,对拼写错误也挺敏感的。

6.优先从业务词汇表中获取

对一个业务,维护一个公共的词汇表,这样一个业务就不会出现好几个名字了,
并且不仅限于前端,还有后端、数据等。

如果采用领域驱动设计的方式,还能让产品也参与到词汇的维护中来。

7.使用对仗词

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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/set
next/previous
up/down
old/new

命名方法

1.驼峰命名法

大驼峰为首字母大写:EmployeeId
小驼峰为首字母小写:employeeId

1
2
3
4
5
6
7
8
9
10
// bad
EmployeeID
UserAPI

// good
EmployeeId
employeeId

UserApi
userApi

2.串行命名法

单词之间通过连字符“-”连接

1
2
background-color
header-logo

3.蛇形命名法

单词之间通过下划线“_”连接,比如“”

1
2
MAX_LIMIT
max_limit

规范

1.类命名是名词,表示一个对象,采用大驼峰命名法:class Account

2.方法命名是动词或动宾短语,表示一个动作,采用小驼峰命名法:function translateArticle()

3.变量命名,采用小驼峰命名法:userName

4.常量命名,采用大写蛇形命名法:MAX_NUM

5.文件模块命名是名词,采用小驼峰命名法:exportExcel.js

6.组件命名是名词,采用大驼峰命名法:UserHome.vue(index.vue除外)

8.图片命名采用串行命名法:add-plus.png

9.目录命名采用串行命名法:user-list

10.路由路径命名小驼峰命名法:/pay/payInfo

11.项目命名采用串行命名法:flow-portal

结语

我们可以使用一些工具来帮助命名:CODELF同义词反义词词典

如果在几个单词之间摇摆不定,就去查看英英释义和例句。

参考资料

  • 《代码整洁之道》
  • 《代码大全2》
  • 《代码之丑》
  • 《代码精进之路》