怎样写好函数？ —— 读《Clean Code》Function一章

Posted on 2019-09-01 Edited on 2019-09-04

曾经看过一种说法，写代码最难的是命名，当时不能理解。这么多年写下来，发现真的是这样，一个好的变量名或者函数名，要简短，又要反应足够的逻辑。确实很难，并不是一句玩笑话。
与此类似的是，如何写好一个函数，也不是那么简单的。曾经我们认为不管代码写成什么样，只要能做到最后的功能，它们就都是一样的。真的是这样吗？
就好比，围棋的布局阶段。你可以说，不管布局怎么下，只要最后赢棋就可以了。但如果布局阶段失败，会让你的中盘官子处处被动。败局从一开始就注定了的。
写代码也是这样，虽然函数可以想怎么写就怎么写，虽然最后的功能可以实现，但是后续的阅读，扩展，重构会越来越困难。最终积重难返，败局也是从一开始就注定了的。
那么如何真正的写好一个函数呢？Uncle Bob用他的经验，给了我们很多操作性很高的指导。

什么样是一个好的函数？

本文完全是Clean Code一书Function一章的摘录。有些加入了我一些自己的认识。本文可以作为文摘阅读，具体可以查阅原文。

small！

Functions should hardly ever be 20 lines long.

Uncle Bob心目中理想的函数的样子：

Every function in this program was just two, or three, or four lines long.

Each was transparently obvious. Each told a story.

And each led you to the next in a compelling order.

That’s how short your functions should be!

实际上，我们很难做到一个函数只有2～4行，尤其像C语言这样强类型的非OO语言。如果刻意的为了短而短，牺牲了可读性，倒是没什么必要。但以我的经验做到不超过20行还是可以做到的。而且应该做到。

Blocks and Indenting

这个是说应该有一个良好且统一的编程格式风格。这个在我经历的公司已经都达成了共识了。所以不再赘述。

Do One Thing

我们知道设计模式中有一个SRP（Single Response Principle）原则。函数也应该符合SRP原则。

FUNCTIONS SHOULD DO ONE THING. THEY SHOULD DO IT WELL. THEY SHOULD DO IT ONLY.

但其实这句话说起来简单，做起来还是很不容易的。

If a function does only those steps that are one level below the stated name of the function, then the function is doing one thing. After all, the reason we write functions is to decompose a larger concept (in other words, the name of the function) into a set of steps at the next level of abstraction.

也就是说，一个函数只对其名称描述的功能做一层分解。
例如：

void handle_command(unsigned char *buf, size_t size)
{
    if (0 = strcmp(buf, "cmd1")) {
        int i = sizeof(struct header);
        buf[i] = 1;
        buf[i+1] = 2;
    }
}

这里应该当判断到命令是cmd1时，不应当在内联命令处理的代码，因为这已经是2级抽象了，应当是：

void handle_command(unsigned char *buf, size_t size)
{
    if (0 = strcmp(buf, "cmd1")) {
        handle_cmd1(buf, size);
    }
}

这就是所谓的一级抽象。特别是你想写这样的分段注释的时候：

public static int[] generatePrimes(int maxValue)
{
    if (maxValue >= 2) // the only valid case
    {
        // declarations
        int s = maxValue + 1;
        
        // size of array
        boolean[] f = new boolean[s];
        int i;
        // initialize array to true.
        for (i = 0; i < s; i++)
            f[i] = true;

        // get rid of known non-primes
        f[0] = f[1] = false;
        ...
    }
}

每一个section就可以提炼成一个函数。当你想用注释把一个函数分成一段一段的，每一段是一个步骤，那么就是机会提炼函数，提供抽象层级。

Switch Statements

这里是说switch泛滥，到处都是长长的对类型switch的语句。而这种情况通常可以由面向对象来解决。

The solution to this problem (see Listing 3-5) is to bury the switch statement in the basement of an ABSTRACT FACTORY, 9 and never let anyone see it.

对于C语言这种弱OO的语言，就要就事论事了。但通常C也是可以应用OO的一些思想来重构这种switch的问题。

My general rule for switch statements is that they can be tolerated if they appear only once, are used to create polymorphic objects, and are hidden behind an inheritance

Use Descriptive Names

这个不再赘述，它有多重要，应该已经得到共识。

Function Arguments

我们现实的编程生活中，函数参数也是非常容易忽视的地方。很多时候，我们为了信息传递的方便，参数一下4，5个，非常常见。却不自知，这样的代码味道很不好。

The ideal number of arguments for a function is zero (niladic). Next comes one (monadic), followed closely by two (dyadic). Three arguments (triadic) should be avoided where possible. More than three (polyadic) requires very special justiﬁcation—and then shouldn’t be used anyway.

在看Uncle Bob的Clean Code之前，其实我也没有过多的关注函数参数的个数，只是偶尔隐隐的觉得调用参数多的函数时，有一种很茫然不知从何开始的感觉。要么翻阅文档，要么查看源码，总归是不那么直接，要费点力气。你看这里作者就明确指出了，参数越少越好（当然这我们也知道），超过3个就要慎重考虑了，尽量避免使用3个及以上个数的参数（作者说的优点夸张，shouldn’t be used anyway，绝对不许使用）。
参数个数多，代表代码有一些坏味道（代码坏味道由Martin Fowler在他的Refactoring一书里提出，即指虽然代码功能没问题，但却在向不好的方向发展，越来越坏，最后就可能出问题了）。

They take a lot of conceptual power.
因为参数不属于函数名表达的抽象层次，所以要知道参数是什么意思，只能看调用时是怎么传入的。然后在阅读函数的时候要时时记得。
Arguments are even harder from a testing point of view. Imagine the difﬁculty of writing all the test cases to ensure that all the various combinations of arguments work properly.
Output arguments are harder to understand than input arguments. When we read a function, we are used to the idea of information going in to the function through arguments and out through the return value. We don’t usually expect information to be going out through the arguments.

一个参数的函数（Monadic Function）

有两种情况，很适合使用单参数函数：

transformation，做转换或者映射，把参数集映射到输出集
event：The overall program is meant to interpret the function call as an event and use the argument to alter the state of the system

标志位参数

Passing a boolean into a function is a truly terrible practice. It immediately complicates the signature of the method, loudly proclaiming that this function does more than one thing.
这时候应该做的是，用不同的函数名来阐述标志位想区分的情况。

两个参数的函数（Dydadic Function）

两个参数要比一个参数难理解的多，因为你需要理解参数的顺序是怎么回事儿。但作者也说了：

Dyads aren’t evil, and you will certainly have to write them. However, you should be aware that they come at a cost and should take advantage of what mechanims may be available to you to convert them into monads.

有两个参数的时候，就要慎重了。总是要尝试找机会转换成单参数的函数。实践来看，想转总是容易的。但是转完之后要符合逻辑语意，有时候就没那么容易了。但总归还是要去尝试，能让函数调用变得更加clean。

三个参数的函数（Triads）

Functions that take three arguments are signiﬁcantly harder to understand than dyads. The issues of ordering, pausing, and ignoring are more than doubled. I suggest you think very carefully before creating a triad.

没啥好说的，三个参数比两个参数引入的额外effort翻倍都不止。所以尽量避免。
作者也提到了一个好的三个参数的例子：assertEquals(1.0, amount, .001)。对float变量的判断，第三个参数引入精度值，这样让调用者返回查看函数原型时，能够得到提醒，对于浮点数来说，相等总是相对的。

Argument Objects

When a function seems to need more than two or three arguments, it is likely that some of those arguments ought to be wrapped into a class of their own.

Reducing the number of arguments by creating objects out of them may seem like cheating, but it’s not. When groups of variables are passed together, they are likely part of a concept that deserves a name of its own.

Verbs and Keywords

这里作者想提醒的是为函数起一个好名字。最好就是用动词+名词的搭配，能阐述的更加清楚。例如：
assertEquals就没有assertExpectedEqualsActual(expected, actual)好。后者体现了参数顺序。
write(name)没有writeField(name)好。因为前者不知道name修饰的是什么，后者告诉我们name是一个field name。

Have No Side Effects

Side effects are lies. Your function promises to do one thing, but it also does other hidden things.
If you must have a temporal coupling, you should make it clear in the name of the function.

函数不要有side effect，也就是focus一件事情。我觉得这里的side effect应该不包括更新全局变量或者类对象的成员变量。

Command Query Separation

Functions should either do something or answer something, but not both. Either your function should change the state of an object, or it should return some information about that object.

这里的意思还是保持SRP，函数要么反应某个object的状态，要么对object做一些操作。对比下面两种写法：

if (setAndCheckIfExists("username", "unclebob"))...

if (attributeExists("username")) {
    setAttribute("username", "unclebob");
    ...
}

Don’t Repeat Yourself

DRY原则，这个也无需赘述

Duplication may be the root of all evil in software.

Prefer Exceptions to Returning Error Codes

使用exception便于在同一个地方处理错误情况。如果用return error code的方式，只能在error发生的地方处理。坏处是，正常逻辑的代码和错误代码会混合在一起。

Thus, a function that handles errors should do nothing else. This implies (as in the example above) that if the keyword try exists in a function, it should be the very ﬁrst word in the function and that there should be nothing after the catch/finally blocks.

处理error的所有代码应该放在一起。不过这里的建议不适用于纯C编程，因为我们没有try-catch。

总结

写好一个函数看似简单，但其实难度不亚于起一个优雅又清晰的名字。Clean Code一书给了不少建议，其实可以反复参阅，勤加重构。
这些建议中，目前我认为重要的是篇首的几个，特别是Function Arguments特别发人警醒。

Small!
Do one thing
One Level of Abstraction per Function
Use Descriptive Names
Function Arguments