如何让代码像一篇优美的文章？

作为程序员，我们一般都会被问到，你的技术栈是什么？你学过什么语言？是的，你学过什么语言？

不管是我们的汉语，还是我们学习的英语，亦或是其他任何一门人类用于交流的语言，他们肯定都有文章这个概念。什么是文章呢？ 首先要有标题，其次要分段落去表达思想，文章要有条理清晰的理念。

那我们学过什么语言呢？为什么C、Java要被称之为语言？是因为它是连通人类与机器、人类与人类之间交流的一种表达方式。我们如果让机器读懂我们所编写的代码，只要告诉机器我们所写代码使用的语言的规则，机器就会很轻松的理解我们的思想（因为机器很聪明呀）。但是如果我们用某种语言写的代码要想让其他人看懂，就不能简简单单的满足规则，满足我们要表达的思想就可以了。我们要把代码写的更清楚，让读者可以在最短的时间、以最轻松的方式读懂你的代码。

那么为什么我们不吸取我们写文章的方式呢？

让句子连在一起组成段落

我们可以试着把方法抽象成文章里的一句话，方法内紧接着调用的另一个方法，就好像是这个句子表达的思想将要突出后面的一句话。所以我们应该把句子2放在句子 1 后面，也就是说我们可以把被调用的方法放在调用方法下面。

我们将每一个方法都遵循此规则，就好像下面这样：

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() {
...
}

当我们阅读这段代码时，心中就会有一个整体感。只需要向读文章一样，上下滑动阅读即可。

有的人可能会说，我通过快捷键一样可以定位到下一个方法。但是当逻辑较复杂时，这样来回定位，上下跳跃会让我们有一种恶心感。所以应该避免它。

定义小范围章节目录

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

就好像下面这样：

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

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

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

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

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

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

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

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

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

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

public class ConcurrentEntirelySearch implements EntirelySearch {
    private static final long MAX_WAIT_MILLISECOND = 1000 * 60 * 2;

    private final List rootCanBeSearch;
    private final ConcurrentEntirelyOpenSearch openSearch;

    public ConcurrentEntirelySearch(List 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 getResultsUntilOneTimeout(KeyT keyT, long timeout, TimeUnit unit) {...}

    @Override
--- public List 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 getResultsUntilOneTimeout(KeyT keyT, long timeout, TimeUnit unit) {
        ...
    }

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

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

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

相信我们谁也不乐意去看由长长的一行组成的一个段落，那么长的一行，谁看了都会恶心。如果我们每一行长度适中，当我们的眼睛由一行转向下一行时，我们大脑也会有一个轻微的缓冲。让人觉得更舒适一点。

所以我们要善于利用这个度，不要让代码过长，但是有时候也可以利用这个度去做inline。只要不超过度就ok。

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

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

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

        assertEquals(new Gold(1000000).getLength(), "1B");
    }

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

下面来看一个反例：

//重构前
int indexPrevious = getIndexByUnit(lastChar + "");
length = Long.parseLong(strLength.substring(0, lastIndex));
firstSetLength(length, indexPrevious);

//重构后
int indexPrevious = getIndexByUnit(lastChar + "");
firstSetLength(Long.parseLong(strLength.substring(0, lastIndex)), indexPrevious);

这里有必要说下度的概念，我认为度不应该是每一行的字符数，比如：我们比较（某一行命名比较长）跟（某一行调用方法比较多）或者（某一行方法的参数比较多）所能承受的最大字符数是不一样的。如果是命名的话，读者能接受的最大长度肯定比（调用方法多的）最大长度要长。

其他

在编写代码时，我们不要一直遵循Clean Code的某些理念，我们要以提高代码可读性为出发点去思考。如果能找到一种办法可以让读者更快的get到你的思想，那么我们应该毫不犹豫的使用它。

下面是一个例子，在重构代码时，我发现了一个方法它很短小，但是却做了两件事，如果把这两件事再分别抽成方法又觉得这样会显得分散，还不如让它们在一起。

当然你有可能会说，那你想一个可以将这两个方法都概括的命名不就好了吗？我想说的是如果我要是想命名会很费劲，因为写代码时候我们往往会在命名上纠结。所以我想到了如下的办法去解决，这样既不用我们想一个总结性的命名，也不用我们抽出方法来。

它就像下面这样：

//调用区
int indexPrevious = getIndexByUnit(lastChar + "");
length = Long.parseLong(strLength.substring(0, lastIndex));
_firstSetLength_secondAddIndexPrevious(length, indexPrevious);

//方法区
private synchronized void _firstSetLength_secondAddIndexPrevious(long length, int indexPrevious) {
    int num = 0;
    while (length >= VALUE_HOW_MUCH_0) {
        length = length/VALUE_HOW_MUCH_0;
        num++;
    }

    setLength((int) length, num);
    this.index += indexPrevious;
}

我把这种命名方式称为“条理性命名”（哈哈，自认为算是一种命名方式哈），我们可以通过“_first”以及“_second”等来表示这个方法里面做了那些事，而不用总结性的去概括它做了什么事。清晰明了，而且省去了我们思考命名的烦恼。

总结

我们在写代码时候，有时间一定要多多琢磨怎样才能让代码更易读，万事以增强代码的可读性为理念。

如果那里写的不好的，欢迎指正。欢迎能有时间能跟大家探讨，互相进步。