工程实践：让变量命名做到"自解释"

　　在上一篇文章中跟大家分享了关于函数命名的一些实践心得，今天我们继续命名这个话题，来讲一讲如何对变量命名。

　　以下是本文的目录大纲：

　　一. 变量命名风格

　　二. 变量命名最高境界

　　三. 变量命名最佳实践

　　若有不正之处请多多谅解，并欢迎批评指正。

　　请尊重作者劳动成果，转载请标明原文链接：

　https://www.cnblogs.com/dolphin0520/p/10639167.html

一.变量命名风格

　　变量命名风格通常会根据不同的变量类型来区分，以Java语言为例，根据变量类型不同有两种命名风格：

1）类成员变量、局部变量

　　类成员变量、局部变量通常采用驼峰命名风格，如下：

String userName;

2）静态成员变量、枚举值、常量

　　静态成员变量、枚举值、常量通常采用所有字母大写、多个单词以英文下划线连接，如：

public static final int MAX_YEARS = 25;

// 建议枚举类都以Enum结尾
enum ColorEnum {
    RED(0, "红色"),
    YELLOW(1, "黄色"),
    GREEN(2, "绿色"),
    WHITE(3, "白色"),
    BLACK(4, "黑色");
    private int code;
    private String name;

    Color(int code, String name) {
        this.code = code;
        this.name = name;
    }
}

二.变量命名最高境界

　　在函数命名那篇中我们说的函数命名最高境界是见字如面，那么对于变量命名来说，最高境界是什么呢？我认为是：自解释，即"代码即注释"。

　　为什么这么说呢，因为通常来说一个函数是会有函数注释的，即使函数名字取的不好，如果注释写的比较清楚，对于后续维护人员来说也是了解函数具体功能的一种方式。

　　而变量则不同，在一个工程里面，变量的数量远远大于函数的数量，所以不太可能对于每个变量都去写注释，所以如果一个工程的变量命名很糟糕，那么对于后续维护人员来说将是毁灭性的打击，因为每读到一个变量，可能就需要去猜测变量的含义，我想没有哪个人愿意读到这样的代码，永远记住一点："代码是写给人看的，不是写给机器看的"。

　　譬如下面这段代码的命名就非常糟糕：

ppn = (cpn > 1) ? (cpn - 1) : cpn;
npn = (cpn < tpn) ? (cpn + 1) : tpn;

p = new Page(ppn, cpn, npn, tpn);

　　上面这段代码估计只有原作者清楚地知道各个变量的含义是啥了，

　　如果修改为下面这种写法，可读性会好很多，并且一目了然，很容易知道其大概意图是计算分页信息：

prePageNum = (curPageNum > 1) ? (curPageNum - 1) : curPageNum;
nextPageNum = (curPageNum < totalPageNum) ? (curPageNum + 1) : totalPageNum;

page = new Page(prePageNum, curPageNum, nextPageNum, totalPageNum);

三.变量命名最佳实践

1）采用名词或者形容词来命名变量

　　变量一般情况下建议使用名词、名字组合或者形容词，因为变量一般形容的是一种事物或者事物的属性，所以用名词或者名词组合更容易让人理解，而形容词一般用于bool类型的变量。

2）避免使用单字母变量，尽量细化变量含义

　　在程序中，尽量避免使用单字母变量，唯一可以接受使用单字母变量的场景只有for循环，不过还是不太推荐在for循环中使用单字母变量(用pos、index比for循环的i、j、k要好很多)。

　　举个例子，比如下面这行代码：

double calConeVolume(double b, double d) {
  return Math.PI * b * b * d / 3;
}

　　咋一看这个函数参数感觉挺清晰，但是一细看，b是什么？d又是什么？如果我要用这个函数，该怎么传参？估计大部人是一脸懵逼状，只能进去看实际的函数实现才知道b是圆锥体半径，d是圆锥体高度；

　　那么怎么优化这段代码命名呢？其实很简单，稍微细化一下变量含义，让变量名自己去表达实际意图：

double calConeVolume(double radius, double height) {
  return Math.PI * radius * radius * height / 3;
}

3）变量命名前后用词需统一

　　在同一个工程或者一个场景下，变量命名风格需前后统一，比如total和sum都能表示总计的意思，那么所有需要用到"总计"含义的地方要么全部使用total、要么全部使用sum。

　　保持前后命名风格统一是保证工程代码良好可读性的关键保证。

4）集合变量用类型或者复数s作为后缀

　　在java中，有很多集合，比如List、Map、Set等，那么集合变量该怎么命名呢？

　　一般可采取两种方式：

使用复数s结尾

List<Student> students = new ArrayList<>();

用集合类型作为后缀

List<Student> studentList = new ArrayList<>();

　　上面两种方式均可，没有比较明显的偏好，根据实际场景决定。第一种方式相对更简洁，第二种在局部作用域里面有多种相关的集合变量时区分度更大，比如：

List<Student> studentList = new ArrayList<>();
Map<Long, Student> studentMap = Maps.newHashMap();

for (Student stu : studentList) {
  studentMap.put(stu.getId, stu);
}

　　我的建议是如果局部作用域只有一种类型的集合，那么推荐使用复数形式；如果局部作用域有多个相关的集合类型，那么推荐用类型结尾。

5）禁止使用is作为bool类型的类成员变量前置

　　在java中，禁止用is作为bool类型的类成员变量的前缀，因为is作为前缀会导致序列化/反序列出现问题，阿里的java代码规范中也明确提到了这一点，所以在写代码的时候最好还是遵守公认的规范，不然哪天说不定就踩坑了。

6）尽量避免使用缩写进行命名

　　有些时候，变量名可能有点长，不利于代码可读性，因此很多时候在写代码的时候喜欢用缩写来命名，但这个不是一个好的习惯，除非使用的缩写是大家都会使用的约定俗称的缩写。

　　比如下面这个命名：

int averageStudentAge;  =>  int avgStudentAge;

　　因为avg大家都知道是average的缩写，所以这么写问题不大，不会引起歧义；

　　但是下面这种缩写命名：

res
tmp
cnt
dep

　　就不是好的缩写命名，因为不同的人阅读可能会有不同的理解：

res => response、resource、result
tmp => temporary、template
cnt => count、content、context

　　附上一些约定俗称的缩写：

7）抛弃掉flag变量

　　国内一些早期的教材上，到处充斥着各种flag风格的变量，这种命名方式对于大型工程简直就是噩梦，比如：

int flag = getDoctorFlag(doctorId);
if (flag == 1) {
  //....
}

　　看到这段代码，读者会有疑问flag变量的含义是什么？flag值为1的时候又代表什么含义？是医生的值班/在岗状态、还是医生的身体状态？估计读者的内心是崩溃的。

　　如果优化成下面这种形式：

DutyStatus doctorDutyStatus = getDoctorDutyStatus(doctorId);
if (doctorDutyStatus == DutyStatus.ONLINE) {
  // ...
}

　　就比上面的形式清晰多了，很容易看出来判断的是医生的值班/在岗状态。

Matrix海 子