JavaScript 变量命名规范总结-蒲公英云

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

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

点击上方程序员成长指北，关注公众号

回复1，加入高级Node交流群

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

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

如果觉得这篇文章还不错

点击下面卡片关注我

来个【分享、点赞、在看】三连支持一下吧