前端代码整洁之道
近读《代码整洁之道》,颇有几分感悟。原著虽是针对java语言撰写,但其中很多的道理在前端亦可套用。以下是个人总结的一些要点和感悟,与诸君共勉。
本文仅针对原著中与前端相关性较大的部分做了总结,仅占原著篇幅的一半左右。如欲了解更多,欢迎阅读原著。
本文中并未呈现细枝末节,关于更详细的例子,建议补充阅读clean-code-js。
命名篇🙋
原则😲
-
简要。
- 二者需兼顾、平衡,说起来简单,做起来就··· ···得慢慢自行体会了。
-
变量名定义使用名词短语。
customerGender
-
函数名定义使用动词短语。
getCustonmerGender
规则😡
-
避免模糊。
- 名称背后所代表的含义范围越小越好。最好是无需注释即可知晓其含义。
- good: gameBoard - ba d: theList
- 名称背后所代表的含义范围越小越好。最好是无需注释即可知晓其含义。
-
避免误导。
- 名称中尽量不要使用容易造成误导的词。比如不要带有list(万一它背后的数据不是list结构呢)。
- good: accountList - ba d: accountList
- 名称中尽量不要使用容易造成误导的词。比如不要带有list(万一它背后的数据不是list结构呢)。
-
避免废话。
- 显而易见的东西不必额外说明。
- good: customerGender - ba d: customerGenderData
- 显而易见的东西不必额外说明。
-
避免自创。
- 不要自己创造单词或使用自己看得懂的缩略语。
- good: timestamp - ba d: ts
- 不要自己创造单词或使用自己看得懂的缩略语。
-
避免搜索不便。
- 尽量不要使用单个单词的变量名称,这样不便于准确搜索,比如代码中既有变量名days、又有变量名workDays。这样在搜索days时,workDays也会被命中。
- good: workDays - ba d: days
- 尽量不要使用单个单词的变量名称,这样不便于准确搜索,比如代码中既有变量名days、又有变量名workDays。这样在搜索days时,workDays也会被命中。
-
避免使用编码。
- 不要自己创造单词或使用自己看得懂的缩略语。
- good: product - ba d: productData ```
- 不要自己创造单词或使用自己看得懂的缩略语。
-
避免一词多义。
- 不要用一个词代表多种含义。比如同时用handler···去表示删除和增加(虽然乍看并没有问题)
- good: delCustomerGender && addCustomerGender - ba d: handlerCustomerGender ```
- 不要用一个词代表多种含义。比如同时用handler···去表示删除和增加(虽然乍看并没有问题)
-
避免一义多词。
- 不要用多个词去代表同一个含义。比如同样要表达增加,不要一会使用add,一会使用append。
- good: addCustomer || appendCustomer - ba d: addCustomer && appendCustomer ```
- 不要用多个词去代表同一个含义。比如同样要表达增加,不要一会使用add,一会使用append。
建议😘
-
换好名任何时候都不晚。
- 一旦想到了更好的名称,就立即替换原名称。
-
刻意套用命名规则。
- 初期要刻意的去套用规范规则,适应之后就会越来越得心应手。
-
不要介意长名称。
- 长而表意清晰名称的名称,远胜于短而表意含糊的名称。
函数篇🙋
规则😡
-
要短小。
- 过长的函数阅读起来难以理解,而且容易头昏眼花(不管你花不花,反正我是花了)。
-
要专一。
- 每个函数只应该做一件事。如果没有,那就拆分。
-
对应一个抽象层。
- 对于类似table > tableHeader 这样两个层级的处理,要交由不同的函数分别来做。
-
参数要尽可能少。
-
参数数量尽量不要多于三个。
- 如果不得不使用多于三个的参数,那就考虑使用参数对象或参数列表。
- 柯里化处理也是个不错的选择。
-
-
不要产生副作用。
- 函数不应做出职责以外的改变。比如checkPassword函数就不应修改password。
-
不要做重复的事。
-
类似的代码如果出现了两次以上,就对其优化。
- 不只是针对JS,HTML、CSS也会出现类似的问题
-
建议😘
-
函数在20行以内。
- 但也不要为了少而少,比如将if...else...这种代码块缩为一行,这样只会适得其反。
-
遵守自顶向下规则。
- 代码书写顺序要与逻辑顺序相符,不要反复横跳。
-
尽量不要使用标识参数。
- 举例来说,前端很容易碰到如下方法,此时传入的参数bool即为一种标识。这种形式的函数一般都不符合单一职责规则。
//eg: function changeLoadingStatus (bool) { if (bool){ loadingStatus = 'open' }else{ loadingStatus = 'close' } } //不如拆分为: function openLoading (bool) { loadingStatus = 'open' } function closeLoading (bool) { loadingStatus = 'close' } //这段代码其实有不合理的地方,此处只为说明情况方便。
注释篇🙋
原则😲
-
注释是代码的补充,而不是代码的翻译。
-
能通过变量名、清晰的代码规则传达的信息,就不要再用注释去做解释。
规则😡
- 不要企图通过多写注释来挽救表意糟糕的代码。
- 多用注释来说明函数背后的意图。
- 注释最好是在说明为什么这么做,而不是说明在做什么。
- 注释不止可以用来做解释,也可以用来做警示。
- 使用TODO注释,来表明待做的处理。
- 函数、文件注释格式最好规范统一。
- 可以使用vscode插件 koroFileHeader。
建议😘
-
在代码注释中添加署名信息必要性不大。(因为编辑者信息我们可以轻松通过git或svn这种源码控制系统得知。)
-
不一定非得要有函数头,表意清晰的函数名远比函数头注释重要。
格式篇🙋
原则😲
- 良好的代码格式可以提升阅读体验。
规则😡
- 区块之间用空白行合理隔开。
- HTML、CSS、JS都应如此。
- 逻辑上相关的代码在距离上也应靠近。
- 保持一致的缩进风格。
- 2格也好4格也罢,贵在全局一致。
- 团队开发中更要注意格式规则上的整齐。
建议😘
- 前端的很多格式问题已可以交由工具解决。
- eslint、preitter·、stylelint、vetur。
错误处理篇🙋
原则😲
- 不要因为错误处理而搞乱了代码逻辑。
规则😡
- 合理使用try-catch-finally语句。
- 在catch中说明异常发生的环境。
- 既不要返回null值,也不要传递null值。
渐进优化篇🙋
原则😲
- 整洁代码并非一蹴而就,渐进优化极其重要。
- 以下规则按重要程度排序:
规则😡
- 必须通过所有测试。
- 务必不要出现重复。
- 尽量表达出程序员的意图。
- 使方法和变量尽可能少。
建议😘
- 渐进优化并不只是注意以上几点就好,在这一过程中,也同样不能忘记我们之前所有的规则和建议。
另附思维导图一张。