作为程序员，我们或许常常会被问到：你都学过什么语言呢？你最擅长的是哪一门语言？是的，一门语言。

这里所提到的语言并非我们的母语汉语，也不是英语亦或其他任何一种用于交流日常工作生活的语言。而是指编程过程中，连通人与机器、人与人之间的一种表达方式。让机器读懂代码很简单，只需注明所用代码的语言规则就好，毕竟机器那么聪明 ：）但是如果想要让其他人看懂，就不能这样简单粗暴了。人是感性与理性结合的动物，优雅“风趣”的表达能够让对方更快、更轻松的读懂你的代码。

既然都是表达内容，那么为什么不用写文章的方式来写代码呢？文章是人们日常用于交流表达的一种方式，那么我们是否可以吸收文章的优势来用在写代码上呢？

image

让句子连在一起组成段落

我们可以试着把方法抽象成文章里的一句话，方法内紧接着调用的另一个方法，就好像是第一句话还需要第二句话去完善一样。所以我们应该把句子2放在句子 1 后面，也就是说我们可以把被调用的方法放在调用方法下面。

同理，一个方法内部两个相邻方法的调用先后顺序就像是文章里两个相邻句子的先后顺序一样。所以我们也应把这种顺序作为方法上下排列的顺序。

那么如果我们不遵循这种规则会怎么样呢？

private void preparePizza(Pizza pizza) {
  getFlour();
}

private void boxPizza(Pizza pizza) {
...
}

public Pizza orderPizza(String type) {
  Pizza pizza = getBasePizza(type);
  preparePizza(pizza);
  boxPizza(pizza);
  return pizza;
}

private Flour getFlour() {
...
}

private Pizza getBasePizza(String type) {
...
} 

上面这段代码方法排序是随意的，我们无法直观的看到方法的执行顺序。就好像是：“再然后我去吃早饭；然后我去洗漱；我早上七点起床”，混乱的顺序增加了我们理解代码的困难度。

如果我们遵循这两种规则来排序方法，那就如下面这样：

public Pizza orderPizza(String type) {
  Pizza pizza;
  pizza = getPizza(type);

  preparePizza();
  boxPizza();
  return pizza;
}

private Pizza getPizza(String type) {
...
}

private void preparePizza() {
  getFlour();
}

private Flour getFlour() {
...
}

private void boxPizza() {
...
}

当我们阅读这段代码时，会觉得这是一个整体，只需要向读文章一样，上下滑动阅读即可。

有的人可能会说，通过快捷键一样可以定位到下一个方法。但是快捷键仅适用于逻辑简单的情况，在复杂的逻辑中来回定位所产生的上下跳跃会让人觉得非常难受，这也是我们应当竭力避免的。

image

定义小范围章节目录

一本书或一篇长文，一般都会有章节目录。就好像一个类中有几个提供给外界调用的public方法，这可以使我们有很好的全局观。所以我们应该把类中一些提供主要功能的对外方法放到一起，这些方法要以功能相近来集聚。

如下：

@Override
public ResultT getAResult(KeyT keySearch) {
  ...
}

@Override
public ResultT getAResultUntilTimeout(KeyT keyT, long timeout, TimeUnit timeUnit) throws TimeoutException {
  ...
}

@Override
public List<ResultT> getResultsUntilOneTimeout(KeyT keyT, long timeout, TimeUnit unit) {
  ...
}

@Override
public List<ResultT> getResultsUntilTimeout(KeyT keyT, long timeout, TimeUnit unit) {
  ...
}

@Override
public List<ResultT> getResultsUntilEnoughOrTimeout(KeyT keyT, int expectNum, long timeout, TimeUnit unit) {
  ...
}

@Override
public List<ResultT> getResultsUntilEnoughOrOneTimeout(KeyT keyT, int expectNum, long timeout, TimeUnit unit) {
  ...
}

@Override
public List<ResultT> getResultsUntilEnough(KeyT keyT, int expectNum) throws TimeoutException {
  ...
}

这是我写的一个search-framework中的部分代码，这些方法都是相近的，所以把它们放到一起。另外我们要小范围的集聚，即把相似的开放式方法放在一起，这些方法的下面就是内部调用的方法，继续遵循“让句子连在一起组成段落”的理念。

image.gif

其实有一种更好的办法，就是可以用一种插件让IDEA自动生成一种目录式方法。这种方法只包含基本信息，没有内部实现，并且我们可以点击目录进入方法的准确位置（准确位置的方法排序遵循段落式描述法）。至于如何让IDEA知道哪些方法应该生成目录式方法，我们或许可以通过某种注解去定义。

那么它看起来就好像下面这样：

public class ConcurrentEntirelySearch<KeyT, ResultT, PathT> implements EntirelySearch<KeyT, ResultT> {
  private static final long MAX_WAIT_MILLISECOND = 1000 * 60 * 2;

  private final List<PathT> rootCanBeSearch;
  private final ConcurrentEntirelyOpenSearch<KeyT, ResultT, PathT> openSearch;

  public ConcurrentEntirelySearch(List<PathT> rootCanBeSearch, SearchModel searchModel) {
    this.rootCanBeSearch = rootCanBeSearch;
    this.openSearch = new ConcurrentEntirelyOpenSearch<>(searchModel);
  }

/** 目录（如何展示细节待设计）*/
  @Override
--- public ResultT getAResult(KeyT keySearch) {...}

  @Override
--- public ResultT getAResultUntilTimeout(KeyT keyT, long timeout, TimeUnit timeUnit) throws TimeoutException {...}

  @Override
--- public List<ResultT> getResultsUntilOneTimeout(KeyT keyT, long timeout, TimeUnit unit) {...}

  @Override
--- public List<ResultT> getResultsUntilTimeout(KeyT keyT, long timeout, TimeUnit unit) {...}
/** 目录完（虚拟内容，可点击跳转至方法）------------------- */

  @Override
  public ResultT getAResult(KeyT keySearch) { // 此为真实方法，非目录
    methodA();      //方法排序遵循上述的 段落式描述法
    methodB();
  }

  private void methodA() {
  ...
  }

  private void methodB() {
  ...
  }
  //下同，方法内调用的方法略
  @Override
  public ResultT getAResultUntilTimeout(KeyT keyT, long timeout, TimeUnit timeUnit) throws TimeoutException {
    ...
  }

  @Override
  public List<ResultT> getResultsUntilOneTimeout(KeyT keyT, long timeout, TimeUnit unit) {
    ...
  }   @Override
  public List<ResultT> getResultsUntilTimeout(KeyT keyT, long timeout, TimeUnit unit) {
    ...
  }
}

这些目录我认为应该放在构造方法的下面，这样看起来更加有条理。

写文章时不要让每一行过长

相信没有人愿意去看由一行行长文所组成的段落，长度适中的段落能够让读者在跳行时有一个休息，也给大脑一个轻微的缓冲，这样的阅读舒适感会高很多。所以我们要善于利用这个度，不要让代码过长，但是有时候也可以利用这个度去做inline，只要不超过那个限度就ok。

image

这个思想是在一次ThoughWorks的活动中受到的启发，inline是很好，但是它不能过度，只要我们遵循“写文章时不要让每一行过长”的理念就ok。让读者得以take a breath。

就好像下面这次重构一样：

//重构前
@Test
public void should_return_1B_given_1000000_length() {
  Gold gold = new Gold(1000000);
  String length = gold.getLength();
  assertEquals("1B", length);
}
//重构后
@Test
public void should_return_1B_given_1000000_length() {
  assertEquals("1B", new Gold(1000000).getLength());
}

上面这个例子就利用了这种理念，在读者读一行代码时，能接受的最多字符是有限的，过长就会产生疲倦感、厌恶感。

下面来看一个反例：

//重构前
int previousNumber = getNumberByUnit(lastIndex);
String target = numberString.substring(0, lastIndex);
compute(Long.parseLong(target), previousNumber);
//重构后
int previousNumber = getNumberByUnit(lastIndex);
compute(Long.parseLong(numberString.substring(0, lastIndex)), previousNumber);

这里有必要解释一下“度”的概念，我认为度不应该以每一行能容纳的字符数来衡量。而是要以 该行内变量或方法命名的长度、该行内嵌套调用的方法数量、该行内调用方法的参数数量 这三点综合去考虑。

“某一行命名比较长” 、 “某一行嵌套调用的方法比较多” 和 “某一行方法的参数比较多” 所能承受的最大字符数是不一样的。比如：读者能接受的“命名比较长”的最大长度跟所能接受的 “调用方法多的” 最大长度所能容纳的字符数肯定不一样，因为命名就算再长点也还像是一句话，我们也还算可以理解，而调用的方法逐渐变多那理解的复杂度就会几何增长。

总结

如文载道，要想让自己的代码发挥更大的影响，就一定要花时间去琢磨怎么把它写的更易读。我们应坚持写“笨”代码的思想，如果代码能像文章那样有条理，有规律可循，那无疑可以增强代码的可维护性。这样的代码阅读起来也会让人更加舒适。

文/ThoughtWorks 郑占鹏