改善代码质量的20条编程规范

墨蓝 2021-09-18 05:50 363阅读 0赞

## 命名 ##

#### 1. 命名多长合适 ####

命名的一个原则就是以能准确达意为目标

#### 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对象这个上下文

#### 3. 命名要可读、可搜索 ####

在命名的时候，最好能符合整个项目的命名习惯。大家都用“selectXXX”表示查询，你就不要用“queryXXX”；大家都用“insertXXX”表示插入一条数据，你就要不用“addXXX”，统一规约是很重要的，能减少很多不必要的麻烦。

## 注释 ##

#### 1. 注释到底该写什么？ ####

注释的目的就是让代码更容易看懂。只要符合这个要求的内容，你就可以将它写到注释里。总结一下，注释的内容主要包含这样三个方面：做什么、为什么、怎么做。我来举一个例子给你具体解释一下。

/**
    * (what) Bean factory to create beans. 
    * 
    * (why) The class likes Spring IOC framework, but is more lightweight. 
    *
    * (how) Create objects from different sources sequentially:
    * user specified object > SPI > configuration > default object.
    */
    public class BeansFactory {
      // ...
    }

*  注释比代码承载的信息更多
 *  注释起到总结性作用、文档的作用
 *  一些总结性注释能让代码结构更清晰

public boolean isValidPasword(String password) {
      // check if password is null or empty
      if (StringUtils.isBlank(password)) {
        return false;
      }
    
      // check if the length of password is between 4 and 64
      int length = password.length();
      if (length < 4 || length > 64) {
        return false;
      }
        
      // check if password contains only a~z,0~9,dot
      for (int i = 0; i < length; ++i) {
        char c = password.charAt(i);
        if (!((c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '.')) {
          return false;
        }
      }
      return true;
    }

#### 2. 注释是不是越多越好？ ####

注释太多和太少都有问题。太多，有可能意味着代码写得不够可读，需要写很多注释来补充。除此之外，注释太多也会对代码本身的阅读起到干扰。而且，后期的维护成本也比较高，有时候代码改了，注释忘了同步修改，就会让代码阅读者更加迷惑。当然，如果代码中一行注释都没有，那只能说明这个程序员很懒，我们要适当督促一下，让他注意添加一些必要的注释。

## 代码风格 ##

#### 1. 类、函数多大才合适？ ####

对于函数代码行数的最大限制，网上有一种说法，那就是不要超过一个显示屏的垂直高度。比如，在我的电脑上，如果要让一个函数的代码完整地显示在 IDE 中，那最大代码行数不能超过 50。这个说法我觉得挺有道理的。因为超过一屏之后，在阅读代码的时候，为了串联前后的代码逻辑，就可能需要频繁地上下滚动屏幕，阅读体验不好不说，还容易出错。

#### 2. 一行代码多长最合适？ ####

在Google Java Style Guide文档中，一行代码最长限制为 100 个字符。不过，不同的编程语言、不同的规范、不同的项目团队，对此的限制可能都不相同。不管这个限制是多少，总体上来讲我们要遵循的一个原则是：一行代码最长不能超过 IDE 显示的宽度。需要滚动鼠标才能查看一行的全部代码，显然不利于代码的阅读。当然，这个限制也不能太小，太小会导致很多稍长点的语句被折成两行，也会影响到代码的整洁，不利于阅读。

#### 3. 善用空行分割单元块 ####

对于比较长的函数，如果逻辑上可以分为几个独立的代码块，在不方便将这些独立的代码块抽取成小函数的情况下，为了让逻辑更加清晰，除了上一节课中提到的用总结性注释的方法之外，我们还可以使用空行来分割各个代码块。  
除此之外，在类的成员变量与函数之间、静态成员变量与普通成员变量之间、各函数之间、甚至各成员变量之间，我们都可以通过添加空行的方式，让这些不同模块的代码之间，界限更加明确。写代码就类似写文章，善于应用空行，可以让代码的整体结构看起来更加有清晰、有条理。

#### 4. 四格缩进还是两格缩进？ ####

Java两格缩进

#### 5. 大括号是否要另起一行？ ####

Java 一般是同一行

#### 6. 类中成员的排列顺序 ####

可以参考一些 order 的插件顺序（idea）

## 编程技巧 ##

#### 1. 把代码分割成更小的单元块 ####

大部分人阅读代码的习惯都是，先看整体再看细节。所以，我们要有模块化和抽象思维，善于将大块的复杂逻辑提炼成类或者函数，屏蔽掉细节，让阅读代码的人不至于迷失在细节中，这样能极大地提高代码的可读性。不过，只有代码逻辑比较复杂的时候，我们其实才建议提炼类或者函数。毕竟如果提炼出的函数只包含两三行代码，在阅读代码的时候，还得跳过去看一下，这样反倒增加了阅读成本。

// 重构前的代码
    public void invest(long userId, long financialProductId) {
      Calendar calendar = Calendar.getInstance();
      calendar.setTime(date);
      calendar.set(Calendar.DATE, (calendar.get(Calendar.DATE) + 1));
      if (calendar.get(Calendar.DAY_OF_MONTH) == 1) {
        return;
      }
      //...
    }
    
    // 重构后的代码：提炼函数之后逻辑更加清晰
    public void invest(long userId, long financialProductId) {
      if (isLastDayOfMonth(new Date())) {
        return;
      }
      //...
    }
    
    public boolean isLastDayOfMonth(Date date) {
      Calendar calendar = Calendar.getInstance();
      calendar.setTime(date);
      calendar.set(Calendar.DATE, (calendar.get(Calendar.DATE) + 1));
      if (calendar.get(Calendar.DAY_OF_MONTH) == 1) {
       return true;
      }
      return false;
    }

#### 2. 避免函数参数过多 ####

我个人觉得，函数包含 3、4 个参数的时候还是能接受的，大于等于 5 个的时候，我们就觉得参数有点过多了，会影响到代码的可读性，使用起来也不方便。针对参数过多的情况，一般有 2 种处理方法。

*  考虑函数是否职责单一，是否能通过拆分成多个函数的方式来减少参数。示例代码如下所示：

public User getUser(String username, String telephone, String email);
    
    // 拆分成多个函数
    public User getUserByUsername(String username);
    public User getUserByTelephone(String telephone);
    public User getUserByEmail(String email);

*  将函数的参数封装成对象。示例代码如下所示：

public void postBlog(String title, String summary, String keywords, String content, String category, long authorId);
    
    // 将参数封装成对象
    public class Blog {
      private String title;
      private String summary;
      private String keywords;
      private Strint content;
      private String category;
      private long authorId;
    }
    public void postBlog(Blog blog);

#### 3. 勿用函数参数来控制逻辑 ####

不要在函数中使用布尔类型的标识参数来控制内部逻辑，true 的时候走这块逻辑，false 的时候走另一块逻辑。这明显违背了单一职责原则和接口隔离原则。我建议将其拆成两个函数，可读性上也要更好。我举个例子来说明一下。

public void buyCourse(long userId, long courseId, boolean isVip);
    
    // 将其拆分成两个函数
    public void buyCourse(long userId, long courseId);
    public void buyCourseForVip(long userId, long courseId);

不过，如果函数是 private 私有函数，影响范围有限，或者拆分之后的两个函数经常同时被调用，我们可以酌情考虑保留标识参数。示例代码如下所示：

// 拆分成两个函数的调用方式
    boolean isVip = false;
    //...省略其他逻辑...
    if (isVip) {
      buyCourseForVip(userId, courseId);
    } else {
      buyCourse(userId, courseId);
    }
    
    // 保留标识参数的调用方式更加简洁
    boolean isVip = false;
    //...省略其他逻辑...
    buyCourse(userId, courseId, isVip);

除了布尔类型作为标识参数来控制逻辑的情况外，还有一种“根据参数是否为 null”来控制逻辑的情况。针对这种情况，我们也应该将其拆分成多个函数。拆分之后的函数职责更明确，不容易用错。具体代码示例如下所示：

public List<Transaction> selectTransactions(Long userId, Date startDate, Date endDate) {
      if (startDate != null && endDate != null) {
        // 查询两个时间区间的transactions
      }
      if (startDate != null && endDate == null) {
        // 查询startDate之后的所有transactions
      }
      if (startDate == null && endDate != null) {
        // 查询endDate之前的所有transactions
      }
      if (startDate == null && endDate == null) {
        // 查询所有的transactions
      }
    }
    
    // 拆分成多个public函数，更加清晰、易用
    public List<Transaction> selectTransactionsBetween(Long userId, Date startDate, Date endDate) {
      return selectTransactions(userId, startDate, endDate);
    }
    
    public List<Transaction> selectTransactionsStartWith(Long userId, Date startDate) {
      return selectTransactions(userId, startDate, null);
    }
    
    public List<Transaction> selectTransactionsEndWith(Long userId, Date endDate) {
      return selectTransactions(userId, null, endDate);
    }
    
    public List<Transaction> selectAllTransactions(Long userId) {
      return selectTransactions(userId, null, null);
    }
    
    private List<Transaction> selectTransactions(Long userId, Date startDate, Date endDate) {
      // ...
    }

#### 4. 函数设计要职责单一 ####

对于函数的设计来说，更要满足单一职责原则。相对于类和模块，函数的粒度比较小，代码行数少，所以在应用单一职责原则的时候，没有像应用到类或者模块那样模棱两可，能多单一就多单一。

public boolean checkUserIfExisting(String telephone, String username, String email)  { 
      if (!StringUtils.isBlank(telephone)) {
        User user = userRepo.selectUserByTelephone(telephone);
        return user != null;
      }
      
      if (!StringUtils.isBlank(username)) {
        User user = userRepo.selectUserByUsername(username);
        return user != null;
      }
      
      if (!StringUtils.isBlank(email)) {
        User user = userRepo.selectUserByEmail(email);
        return user != null;
      }
      
      return false;
    }
    
    // 拆分成三个函数
    public boolean checkUserIfExistingByTelephone(String telephone);
    public boolean checkUserIfExistingByUsername(String username);
    public boolean checkUserIfExistingByEmail(String email);

#### 5. 移除过深的嵌套层次 ####

代码嵌套层次过深往往是因为 if-else、switch-case、for 循环过度嵌套导致的。我个人建议，嵌套最好不超过两层，超过两层之后就要思考一下是否可以减少嵌套。过深的嵌套本身理解起来就比较费劲，除此之外，嵌套过深很容易因为代码多次缩进，导致嵌套内部的语句超过一行的长度而折成两行，影响代码的整洁。  
解决嵌套过深的方法也比较成熟，有下面 4 种常见的思路。

*  去掉多余的 if 或 else 语句。代码示例如下所示：

// 示例一
    public double caculateTotalAmount(List<Order> orders) {
      if (orders == null || orders.isEmpty()) {
        return 0.0;
      } else { // 此处的else可以去掉
        double amount = 0.0;
        for (Order order : orders) {
          if (order != null) {
            amount += (order.getCount() * order.getPrice());
          }
        }
        return amount;
      }
    }
    
    // 示例二
    public List<String> matchStrings(List<String> strList,String substr) {
      List<String> matchedStrings = new ArrayList<>();
      if (strList != null && substr != null) {
        for (String str : strList) {
          if (str != null) { // 跟下面的if语句可以合并在一起
            if (str.contains(substr)) {
              matchedStrings.add(str);
            }
          }
        }
      }
      return matchedStrings;
    }

*  使用编程语言提供的 continue、break、return 关键字，提前退出嵌套。代码示例如下所示：

// 重构前的代码
    public List<String> matchStrings(List<String> strList,String substr) {
      List<String> matchedStrings = new ArrayList<>();
      if (strList != null && substr != null){ 
        for (String str : strList) {
          if (str != null && str.contains(substr)) {
            matchedStrings.add(str);
            // 此处还有10行代码...
          }
        }
      }
      return matchedStrings;
    }
    
    // 重构后的代码：使用continue提前退出
    public List<String> matchStrings(List<String> strList,String substr) {
      List<String> matchedStrings = new ArrayList<>();
      if (strList != null && substr != null){ 
        for (String str : strList) {
          if (str == null || !str.contains(substr)) {
            continue; 
          }
          matchedStrings.add(str);
          // 此处还有10行代码...
        }
      }
      return matchedStrings;
    }

*  调整执行顺序来减少嵌套。具体的代码示例如下所示：

// 重构前的代码
    public List<String> matchStrings(List<String> strList,String substr) {
      List<String> matchedStrings = new ArrayList<>();
      if (strList != null && substr != null) {
        for (String str : strList) {
          if (str != null) {
            if (str.contains(substr)) {
              matchedStrings.add(str);
            }
          }
        }
      }
      return matchedStrings;
    }
    
    // 重构后的代码：先执行判空逻辑，再执行正常逻辑
    public List<String> matchStrings(List<String> strList,String substr) {
      if (strList == null || substr == null) { //先判空
        return Collections.emptyList();
      }
    
      List<String> matchedStrings = new ArrayList<>();
      for (String str : strList) {
        if (str != null) {
          if (str.contains(substr)) {
            matchedStrings.add(str);
          }
        }
      }
      return matchedStrings;
    }

*  将部分嵌套逻辑封装成函数调用，以此来减少嵌套。具体的代码示例如下所示：

// 重构前的代码
    public List<String> appendSalts(List<String> passwords) {
      if (passwords == null || passwords.isEmpty()) {
        return Collections.emptyList();
      }
      
      List<String> passwordsWithSalt = new ArrayList<>();
      for (String password : passwords) {
        if (password == null) {
          continue;
        }
        if (password.length() < 8) {
          // ...
        } else {
          // ...
        }
      }
      return passwordsWithSalt;
    }
    
    // 重构后的代码：将部分逻辑抽成函数
    public List<String> appendSalts(List<String> passwords) {
      if (passwords == null || passwords.isEmpty()) {
        return Collections.emptyList();
      }
    
      List<String> passwordsWithSalt = new ArrayList<>();
      for (String password : passwords) {
        if (password == null) {
          continue;
        }
        passwordsWithSalt.add(appendSalt(password));
      }
      return passwordsWithSalt;
    }
    
    private String appendSalt(String password) {
      String passwordWithSalt = password;
      if (password.length() < 8) {
        // ...
      } else {
        // ...
      }
      return passwordWithSalt;
    }

#### 6. 学会使用解释性变量 ####

常用的用解释性变量来提高代码的可读性的情况有下面 2 种。

*  常量取代魔法数字。示例代码如下所示：

public double CalculateCircularArea(double radius) {
      return (3.1415) * radius * radius;
    }
    
    // 常量替代魔法数字
    public static final Double PI = 3.1415;
    public double CalculateCircularArea(double radius) {
      return PI * radius * radius;
    }

*  使用解释性变量来解释复杂表达式。示例代码如下所示：

if (date.after(SUMMER_START) && date.before(SUMMER_END)) {
      // ...
    } else {
      // ...
    }
    
    // 引入解释性变量后逻辑更加清晰
    boolean isSummer = date.after(SUMMER_START)&&date.before(SUMMER_END);
    if (isSummer) {
      // ...
    } else {
      // ...
    }

参考王争老师的设计模式之美。