分享 Java 开发可参考的一份命名规范！

前言

设计原则和设计模式，利用好它们可以有效地改善代码质量。但是，这些知识的合理应用非常依赖个人经验，用不好有时候会适得其反。

而我们接下来要讲的编码规范正好相反。编码规范大部分都简单明了，在代码细节方面，能立竿见影地改善质量。除此之外，持续低层次、小规模重构依赖的基本上都是编码规范，这也是改善代码可读性的有效手段。

关于编码规范、如何编写可读代码，很多书籍已经讲得很好了。不过，这里我根据我自己的开发经验，总结罗列了 20 条我个人觉得最好用的编码规范。掌握这 20 条编码规范，能你最快速地改善代码质量。内容比较多：命名与注释（Naming and Comments）、代码风格（Code Style）和编程技巧（Coding Tips）。

命名

大到项目名、模块名、包名、对外暴露的接口，小到类名、函数名、变量名、参数名，只要是做开发，我们就逃不过 “起名字” 这一关。命名的好坏，对于代码的可读性来说非常重要，甚至可以说是起决定性作用的。除此之外，命名能力也体现了一个程序员的基本编程素养。这也是我把 “命名” 放到第一个来讲解的原因。

取一个特别合适的名字是一件非常有挑战的事情，即便是对母语是英语的程序员来说，也是如此。而对于我们这些英语非母语的程序员来说，想要起一个能准确达意的名字，更是难上加难了。

实际上，命名这件事说难也不难，关键还是看你重不重视，愿不愿意花时间。对于影响范围比较大的命名，比如包名、接口、类名，我们一定要反复斟酌、推敲。实在想不到好名字的时候，可以去 GitHub 上用相关的关键词联想搜索一下，看看类似的代码是怎么命名的。

那具体应该怎么命名呢？好的命名有啥标准吗？接下来，我就从 4 点来讲解我的经验。

1. 命名多长最合适？

在过往的团队和项目中，我遇到过两种截然不同的同事。有一种同事特别喜欢用很长的命名方式，觉得命名一定要准确达意，哪怕长一点也没关系，所以，这类同事的项目里，类名、函数名都很长。另外一种同事喜欢用短的命名方式，能用缩写就尽量用缩写，所以，项目里到处都是包含各种缩写的命名。你觉得这两种命名方式，哪种更值得推荐呢？

在我看来，尽管长的命名可以包含更多的信息，更能准确直观地表达意图，但是，如果函数、变量的命名很长，那由它们组成的语句就会很长。在代码列长度有限制的情况下，就会经常出现一条语句被分割成两行的情况，这其实会影响代码可读性。

实际上，在足够表达其含义的情况下，命名当然是越短越好。但是，大部分情况下，短的命名都没有长的命名更能达意。

所以，很多书籍或者文章都不推荐在命名时使用缩写。对于一些默认的、大家都比较熟知的词，我比较推荐用缩写。这样一方面能让命名短一些，另一方面又不影响阅读理解，比如，sec 表示 second、str 表示 string、num 表示 number、doc 表示 document。

除此之外，对于作用域比较小的变量，我们可以使用相对短的命名，比如一些函数内的临时变量。相反，对于类名这种作用域比较大的，我更推荐用长的命名方式。

总之，命名的一个原则就是以能准确达意为目标。不过，对于代码的编写者来说，自己对代码的逻辑很清楚，总感觉用什么样的命名都可以达意，实际上，对于不熟悉你代码的同事来讲，可能就不这么认为了。所以，命名的时候，我们一定要学会换位思考，假设自己不熟悉这块代码，从代码阅读者的角度去考量命名是否足够直观。

2. 利用上下文简化命名

我们先来看一个简单的例子。

public class User {

  private String userName;

  private String userPassword;

  private String userAvatarUrl;

  //...

}

在 User 类这样一个上下文中，我们没有在成员变量的命名中重复添加 “user” 这样一个前缀单词，而是直接命名为 name、password、avatarUrl。在使用这些属性时候，我们能借助对象这样一个上下文，表意也足够明确。具体代码如下所示：

User user = new User();

user.getName(); // 借助 user 对象这个上下文

除了类之外，函数参数也可以借助函数这个上下文来简化命名。关于这一点，我举了下面这个例子，你一看就能明白，我就不多啰嗦了。

public void uploadUserAvatarImageToAliyun(String userAvatarImageUri);

// 利用上下文简化为：

public void uploadUserAvatarImageToAliyun(String imageUri);

3. 命名要可读、可搜索

首先，我们来看，什么是命名可读。先解释一下，我这里所说的 “可读”，指的是不要用一些特别生僻、难发音的英文单词来命名。

我们再来讲一下命名可搜索。我们在 IDE 中编写代码的时候，经常会用 “关键词联想” 的方法来自动补全和搜索。

比如，键入某个对象 “.get”，希望 IDE 返回这个对象的所有 get 开头的方法。

再比如，通过在 IDE 搜索框中输入 “Array”，搜索 JDK 中数组相关的类。所以，我们在命名的时候，最好能符合整个项目的命名习惯。

大家都用 “selectXXX” 表示查询，你就不要用 “queryXXX”；大家都用 “insertXXX” 表示插入一条数据，你就要不用 “addXXX”，统一规约是很重要的，能减少很多不必要的麻烦。

4. 如何命名接口和抽象类？

对于接口的命名，一般有两种比较常见的方式。一种是加前缀 “I”，表示一个 Interface。比如 IUserService，对应的实现类命名为 UserService。另一种是不加前缀，比如 UserService，对应的实现类加后缀 “Impl”，比如 UserServiceImpl。

对于抽象类的命名，也有两种方式，一种是带上前缀 “Abstract”，比如 AbstractConfiguration；另一种是不带前缀 “Abstract”。实际上，对于接口和抽象类，选择哪种命名方式都是可以的，只要项目里能够统一就行。

重点总结

好了，今天的内容到此就讲完了。我们来一块总结回顾一下，你需要掌握的重点内容。

关于命名

• 命名的关键是能准确达意。对于不同作用域的命名，我们可以适当地选择不同的长度。作用域小的变量（比如临时变量），可以适当地选择短一些的命名方式。除此之外，命名中也可以使用一些耳熟能详的缩写。

• 我们可以借助类的信息来简化属性、函数的命名，利用函数的信息来简化函数参数的命名。

• 命名要可读、可搜索。不要使用生僻的、不好读的英文单词来命名。除此之外，命名要符合项目的统一规范，不要用些反直觉的命名。

• 接口有两种命名方式：一种是在接口中带前缀 “I”；另一种是在接口的实现类中带后缀 “Impl”。对于抽象类的命名，也有两种方式，一种是带上前缀 “Abstract”，一种是不带前缀。这两种命名方式都可以，关键是要在项目中统一。

 

有收获？老铁们可以来我的官网：java实验室

关注我的公众号，你想要的Java知识文章都有：