代码整洁之道

• 命名
• 函数
• 注释
• 格式

为了降低与优化代码维护的成本，我们制定了一系列的规则与框架，甚至这些框架中建议我们写出降低程序运行效率的代码

为了写出简单易懂可维护的代码，为了成为更好的程序员，我们应该遵守以下的规则

命名

我们需要给变量、函数、参数、类与封包命名

• 名副其实：不要使用 d、o、a 什么的，使用更加多的字符尽可能描述被描述者的作用
• 避免误导：命名时避免使用与本意相悖的词。使用accountList来指一组账号，除非它真的是List类型。如果容纳账号的容器是Set，那就会引起错误的判断
• 魔法值使用静态常量：单字母名称和数字常量有个问题，很难在一大篇文字中找出。找MAX_CLASS_PER_STUDENT很容易，想找数字7就很麻烦。单字母名称仅用于短方法中的本地变量。名称应与其作用域相对应，比如在一个类中经常使用的，就可以通过大写字母的方式来表示
• 避免使用编码：反例：变量名加入成员前缀 m_name 表示接口时加上I字母 接口名：IShapeFactory
• 避免思维映射：在循环体中通过变量来判断条件时，使用i,j或者k就比其他字母好。千万别用小写字母l和打字字母O
• 类名应该是每次或者名词短语，而方法名则应当是动词或者动词短语
• 给每一个抽象概念选一个词，并且一以贯之

函数

• 函数越短小越好，比如 if/else/while 语句的代码块应该只有一行，该行应该是一个函数调用语句。函数的缩进层级不应该多于一层或两层
• 一个函数只做一件事
• 使用描述性的名称，函数越短小、功能越集中，就越便于取个好名字
• 关于函数参数，应该尽量控制在三个以内，一个最好。如果入参过多，应该将他们用一个实体类封装起来。别用标识参数，向函数传入bool值是不好的，这意味着函数不止做一件事。可以将此函数拆成两个
• 使用异常代替返回错误码，DDD 中也这么建议，在 app 层以及以下的层级，应该直接抛出异常
• 不要写重复代码，重复是软件中一切邪恶的根源。当算法改变时需要修改多处地方
• 写函数时，可以使用一个函数先写一个整体的业务逻辑，写完之后进行拆分

注释

• 若编程语言足够有表现力，我们就不需要注释。注释总是一种失败，因为代码在演化，注释却不总是随之变动，同时不准确的注释比没注释坏的多
• 用代码来阐述，只有在不可避免的情况下才使用注解
• 一些显而易见容易理解的方法不要用注解
• 好注释会提供基本信息，如解释某个抽象方法的返回值；对意图的解释，反应了作者某个决定后面的意图；阐释。把某些晦涩的参数或者返回值的意义翻译成可读的形式(更好的方法是让它们自身变得足够清晰，但是类似标准库的代码我们无法修改)

格式

垂直格式

• 短文件比长文件更易于理解。平均200行，最多不超过500行的单个文件可以构造出色的系统
• 紧密相关的代码应该互相靠近，例如一个类里的属性之间别用空白行隔开，变量声明应尽可能靠近其使用位置：循环中的控制变量应该总是在循环语句中声明。
• 成员变量应该放在类的顶部声明，不要四处放置
• 如果某个函数调用了另外一个，就应该把它们放在一起。我们希望底层细节最后展现出来，不用沉溺于细节，所以调用者尽可能放在被调用者之上
• 执行同一基础任务的几个函数应该放在一起，比如构造函数、get、set 方法等

水平格式

• 一行代码不必死守80字符的上限，偶尔到达100字符不超过120字符即可
• 区隔与靠近: 空格强调左右两边的分割。赋值运算符两边加空格，函数名与左圆括号之间不加空格，乘法运算符在与加减法运算符组合时不用加空格(a*b - c)
• 不必水平对齐。例如声明一堆成员变量时，各行不用每一个单词都对齐。
• 短小的if、while、函数里最好也不要违反缩进规则，不要这样：
  if (xx == yy) z = 1;
• Ctrl + Alt + L 能解决大多数水平格式问题