JavaScript 变量命名

原创大美字节前端 ByteFE

计算机科学中只有两个难题：缓存失效和命名。 —— Phil Karlton

任何人都能写出计算机能够理解的代码，只有好程序员才能写出人能够理解的代码。—— Martin Flower

好的代码读起来如同在读一段文章：

function startEditing() {
  if (user.canEdit(currentDocument)) {
    editorControl.setEditMode(true);
    setButtonDown(btnStartEditing);
  }
}

"牛逼"的代码五花八门，这里来段非常牛逼的大家感受下：

const john = new Lady('lily'); 
console.log(john.name); // 当看到控制台输出 "rose" 你是什么感受？

再看一个变量名逐步迭代的过程：

// bad
const fruit = ['apple', 'banana'];

// ok
const fruitArr = ['apple', 'banana'];

// good
const fruits = ['apple', 'banana'];

// great
const fruitNames = ['apple', 'banana'];

const fruits = [
  { name: 'apple', color: 'red' },
  { name: 'banana', color: 'yellow' },
];

看完以上几个示例，我们就知道自己在变量命名这么一件简单的事情上达到了什么层次。当然，其实这个”小事“并不简单，且很重要。本文从「符合命名规范」和「有意义的命名」两个维度，提出了一些实操建议，欢迎拍砖。

符合规范的命名 Comply with naming conventions

用小驼峰形式命名 Use (lower) camelCase

第一个字母小写，剩下的每个单词的首字母大写。

常量可以采用全大写的形式，但普通的`const`修饰的变量不应该大写 Capitalize constant values (if you want)

const HOURS_IN_DAY = 24;
const USER_AGE = 30;

// bad 下面这些并不是常量，只是不会被修改的变量
const USER = findUser();
const TODAY = new Date();

另外附带说明下，代码里应该避免使用魔法数字。

两个字母的缩略词都大写，大于两个则改驼峰 Capitalize two-letter acronyms

IO
AppID

// bad
Io
APPID

下划线是有特定意义的，不要乱用 Avoid underscores in your names

this._myPrivateMethod = function () { /* ... */ };

// bad
const _someGlobalVar = 1;

有意义的命名 Be expressive

Most of these conventions are not for you today, but instead, for you and the people reading your code tomorrow.

使用具描述性的名字 Use meaningful names

这一条包含的信息比较宽泛，这里稍微再展开下：

命名要精确表意，不能太宽泛，更不能词不达意

同一个事物可能有多个单词适配，选最合适的
同一个词有多种含义

使用业务术语。应避免从电脑的视角去命名，而是应该从人类认识事物的角度去命名
尽量避免用缩略语
避免使用黑话。我知道你是业内大佬，但我是小菜菜
单词拼拼对。推荐安装「Code Spell Checker」或其他类似插件

getUserPosts

// bad 含义过于宽泛，不精确
getUserData
getUserInfo

// bad 不要用单个单词的变量，如果只是很小的范围内使用的临时变量则无大碍
global.d = new Date()

用词应尽量精简，无法精简长些也无妨，不能为了精简而放弃语义 When in doubt, favor descriptive over concise

findUserByNameOrEmail
setUserLoggedInTrue

// bad 选词应该尽量精简，但必须保证语义的确定性
findUser

getUserFriend

// bad "FromDatabase" 提供了多少附加信息? 这种可以精简掉
getUserFriendFromDatabase

在上下文中保证意义明确 Be meaningful within their context

这一条可以认为是上面两条的结合，命名不应该重复上下文信息

Class Employee {
  constructor (name) {
    // good
    this.name = name;
    // bad 因为本身就处在 Employee 这个上下文中，信息冗余
    this.employeeName = name;
  }
}

// 这里在 name 前加 employee 是有必要的，因为已经脱离了 Employee 这个上下文
const employeeName = new Employee('gavin').name;

保证动词的统一性 Use consistent verbs per concept

常用的动词有get set read create add update reset delete remove等。

getQuestion
getUserPosts
getUsers

// bad 有很多近意动词，选一个一直用，不要变来变去
getQuestion
returnUsers
retrieveUsers

函数或方法名尽量采用动词或判断性词汇 Use verbs for function names

函数名一般由一个动词加一个名词组成，如 getUser getInfo isArray。

getFullYear()  // 取值
toString()     // 转换
isArray()      // 判断

布尔值的命名 Make booleans that read well in if-then statements

布尔值一般用is can has need等助动词开头，如 isVisible hasLicense canEvaluate shouldAbort。返回布尔值的函数或方法，命名规则相同，如 Array.isArray(arr)。但这样容易出现函数名和变量名冲突的情况，这个时候可以在函数前加check get等区分。

const hasApple = checkHasApple(fruits, 'apple');

// hasApple       是否包含苹果
// checkHasApple  判断是否包含苹果

数值的命名

首选有意义的简短命名，如 width length count，如果没有合适的就采用 numberOfXXX xxxCount 之类的通用命名

width
length
total

maxWidth

numberOfErrors
errorCount

类名用名词 Use nouns for class names

class Car { }
new User()

// bad 类本来就是一类事物的抽象，加动词干啥
class MakeCar { }

字典(Map)的命名

推荐使用 valuesByKey 的方式，如 usersByID。

 const usersByID = {
   id12345: { name: 'byted', age: 9 },
   // ...
 };

 // bad
values  // 提供的信息不够充分
keysToValuesMap  // 名字里不要体现类型，类型信息交给 TypeScript 记吧
mapOfKeysToValues
mapFromKeysToValues

参考资料

https://medium.freecodecamp.org/javascript-naming-conventions-dos-and-don-ts-99c0e2fdd78a?gi=6fd69ae402f7
https://hackernoon.com/the-art-of-naming-variables-52f44de00aad
https://wiki.c2.com/?GoodVariableNames

继续滑动看下一个