• 不恰当的信息 注释只应该描述有关代码和设计的技术性信息，而不是那些本应该在源代码控制系统中保存的信息。
• 废弃的注释 注释很快会过时。废弃的注释应及时删除
• 冗余注释 若果注释解释的是一目了然的东西，就是多余的
• 糟糕的注释 如果值得编写注释就好好写，保证正确的语法和拼写
• 注释掉的代码 注释掉的代码吗污染了所属模块，放散了注意力。应该删除！

环境

• 需要多步才能实现的构建 构建系统应该是单步的小操作——应当能够用单个命令签出系统，并用单个指令构建
• 需要多步才能做到的测试 应该发出单个指令就可以运行全部单元测试

函数

• 过多的参数 函数参数应该少
• 输出参数 输出参数违反直觉。若果函数非要修改某东西的状态，就修改它所在对象的状态
• 标识参数 布尔值参数的存在就意味着函数不止做了一件事，应该消灭
• 死函数 永不调用的函数应该丢弃

一般性问题

• 一个源文件中存在多种语言 理想的源文件有且仅有一种语言
• 明显的行为未被实现 函数或类应该实现其他程序员有理由期待的行为。通过函数名的直觉应该能够理解函数的行为
• 不正确的边界行为 代码应该在所有的边界情况下都能工作。别依赖直觉。探寻每种边界条件，并编写测试
• 忽视安全 不要忽视编译器的警告和错误
• 重复 重复的代码，意味着遗漏了抽象。尽可能找到重复并消除它
• 在错误的抽象层次上的代码 创建分离较高层级一般性概念与较低层级细节概念的抽象模型。所有较低层级概念放在派生类中，所有较高层级概念放在基类中
• 基类依赖于派生类 如果看到基类提到派生类名称，就可能出问题了
• 信息过多 设计良好的模块有着非常小的接口。应该限制类或模块中暴露的接口数量。
• 死代码 不执行的代码应该从系统中删除
• 垂直分割 变量和函数应该在靠近被使用的地方定义
• 前后不一致 消息选择约定，一旦选中，就消息持续遵循
• 混淆视听 保存源代码整洁，良好的组织
• 晦涩的意图 代码要尽可能居有表达力。联排表达式、匈牙利标记法和魔术数都遮盖了作者的意图
• 位置错误的权责 代码应该放在读者自热而然期待它所在的位置
• 不恰当的静态方法 倾向于选用非静态函数。如果的确要静态函数，确保没机会打算让它有多态行为
• 使用解释下变量 把计算过程打散成一系列良好命名的中间值，不透明的模块就会突然变得透明
• 函数应该表达其行为 应该能从函数调用中看出函数的行为
• 理解算法
• 用命名常量代替魔术数 魔术数现在不仅指数字，泛指任何不能自我描述的符号
• 准确 对自己做的决定，确认足够准确。代码的执行要能保证准确性
• 结构甚于约定 命名约定很好，但却次于强制性的结构
• 封装条件 应该把解释了条件意图的函数抽离出来
• 避免否定性条件 否定式条件要比肯定式难理解，尽可能将条件表示为肯定形式
• 函数只做一件事情
• 函数应该只在一个抽象层次上 函数中的语句应该在同一抽象层级上，该抽象层级应该是函数名所示操作的下一层。
• 在较高层次放置可配置数据 位于较高层级的配置性常量易于修改。它们向下贯穿应用程序。应用程序的较低层级并不拥有这些常量的值
• 避免传递浏览 不要让某个模块了解太多其协作者的信息。确保模块只了解其直接协作者而不了解整个系统的浏览图。

名称

• 采用描述性名称
• 避免编码 不应在名称中包括类型或作用范围信息
• 名称应该说明副作用 名称应该说明函数、变量或类的一切信息。不要用名称掩盖副作用

测试

• 测试不足
• 使用覆盖率工具
• 别忽略小测试
• 被忽略的测试就是对不确定事物的疑问
• 测试边界条件
• 全面测试相近的缺陷
• 测试失败的模式有启发性 完整的测试用例、按合理的顺序排列，能暴露出通用性的问题
• 测试覆盖率的模式有启发性
• 测试应该快速

1. 短小精悍
2. 每个空白行都是一条线索，标识出新的独立概念
3. 靠近的代码行则暗示了代码间的紧密关系
4. 变量声明应尽可能靠近其使用位置
5. 实体变量应该在类的顶部声明
6. 被调用函数应该在执行调用函数下面

横向格式

1. 使用空格字符将彼此紧密相关的代码连接起来，也用空格字符把相关性较弱的代码分隔开。

• 在赋值操作符周围加油空格，达到强调的目的

• 不在函数名和左圆括号之间空格

• 空格可以强调其前面的运算符

2. 缩进原则

团队规则

每个程序员都有自己喜欢的格式规则，如果在一个团队中，就是团队说了算！

“别给糟糕的代码加注释——重新写吧”

                                                   Brian W.Kernighan与P.J.Plaugher

1. 注释不能美化糟糕的代码

2. 用代码来阐述

3. 好注释

1. 法律信息
2. 提供信息的注释 如：解释正则表达式的作用
3. 对意图的解释
4. 阐释 对于某些不能修改的代码，阐释其含义
5. 警示
6. TODO注释 TODO是程序员认为应该做，但由于某些原因目前还没做的工作
7. 放大 放大某种看来不合理之物的重要性

4. 坏注释

1. 喃喃自语 仅只是因为觉得应该或者因为过程需要就添加注释
2. 多余的注释
3. 误导性的注释 注释往往不够精确
4. 循规式注释
5. 日志式注释
6. 废话式注释
7. 能用函数或变量时就别用注释
8. 位置标记 不要滥用标记栏
9. 括号后面的注释 如：标记循环结束的括号 //while
10. 归属或署名 源代码控制系统是这类信息最好的归属地
11. 注释掉的代码
12. HTML注释
13. 非本地信息
14. 信息过多
15. 不明显的联系 注释及其描述的代码之间的联系应该显而易见
16. 函数头注释

每个函数都一目了然。每个函数都只做一件事。并且每个函数都依序把你带到下一个函数。这就是函数应该达到的短小程度。函数的代码块缩进层级不该多于一层或两层。这样的函数易于阅读和理解。

2. 只做一件事

函数应该做一件事。做好这件事。只做一件事。函数只是做了该函数名下同一抽象层上的步骤，则函数还是只做了一件事。

3. 每个函数一个抽象层级

自顶向下读代码——向下规则：要让每个函数后面都跟着位于下一抽象层级的函数，这样，在查看函数列表时，就能按照抽象层级向下阅读了。

4. 使用描述性名称

长而具有描述性的名称要比短而令人费解的名称好。长而具有描述性的名称，要比描述性的注释好。

5. 函数参数

最理想的参数数量是零。参数与函数名处在不同的抽象层级，它要求你了解目前并不特别重要的细节。从测试角度看，参数越多越难测试。

6. 无副作用

函数承诺只做一件事，但还是会做其他被藏起来的事，这些事都是具有破坏性的，可能导致古怪的时序性耦合及顺序依赖。

7. 分割指令与询问

函数要么做什么事，要么回答什么事，但二者不可兼得。

8. 使用异常替代返回错误码

使用异常处理替代返回错误码，错误处理代码能从主路径代码中分离出来。

• 抽离try/catch代码块，它们把错误处理与正常流程混为一谈。下面的写法更优雅：

   public void delete(){
       try{
           deletePage();
       }
       catch (Exception e){
           logError(e);
       }

   }
   private void logError(Exception e)
   { }
  private void deletePage()
   { }

• 错误处理就是一件事

9. 别重复自己

10. 如何写出这样的代码：重构！！

• 选个好名字要花时间，但省下来的时间比花掉的多
• 一旦发现有更好的名称，就换掉旧的

2. 避免误导

• 避免留下隐藏代码本意的错误线索
• 避免使用与本意相悖的词
• 如：不用accountList来指代一组账号，出非它真的是List类型

3. 做有意义的区分

• 命名并不仅仅只是为满足编译器的需要
• 如：一个ProductInfo类和ProductData类，它们名称虽然不同，意思却无区别。

4. 使用读得出来的名称

• 不要随意自造词

5. 使用可搜索的名称

• 长名称胜于短名称，搜得到的名称胜于用自造编码代写的名称
• 单字母名称仅用于短方法中的本地变量
• 名称长短与其作用域大小相对应

6. 避免使用编码

1. 1. 匈牙利标记法（HN） 在现代编译器的情况下，已经过时了
   2. 成员前缀 应当把类和函数做得足够小，消除对成员前缀的需要
   3. 接口和实现 接口的前导字母I被滥用。通常并不想让用户知道提供使用的是接口

7. 避免思维映射

• 不应当让读者在脑中把你的名称翻译为他们熟知的名称
• 这种问题经常出现在选择是使用问题域术语还是解决方案领域术语时

8. 类名

• 类名和对象名应该是名词或名词短语
• 类名不应当时动词

9. 方法名

• 方法名应当是动词或动词短语。属性访问器、修改器和断言应该根据其值命名，并可加上get、set和is前缀。

10. 别扮可爱

• 切忌华而不实！言到意到！

11. 每个概念对应一个词

• 给每个抽象概念选一个词，并且一以贯之

12. 别用双关语

• 避免将同一词用于不同目的
• 同一术语用于不同概念，就算是双关语了

13. 使用解决方案领域名称

• 使用计算机科学术语，尽量不使用用所涉领域名称来命名。因为只有程序员会读你的代码。

14. 使用源自所涉问题领域的名称

• 如果不能用程序员熟悉的术语来给手头的工作命名，就采用所涉问题领域的名称
• 与所涉问题领域更为贴近的代码，应当采用源自问题领域的名称

15. 添加有意义的语境

• 很少有名称能自我说明的。因此，需要用有良好命名的类、函数或命名空间来放置名称，给读者提供语境。

16. 不要添加没用的语境