《代码整洁之道》阅读笔记

整洁或好代码的定义

• 参考多位业界大神著作内的定义

命名

• 命名应该有意义，需要表达出该变量或类等的功能、价值。
• 不应存在可能误导的命名。
• 命名要做出有意义的区分，避免做类似xxxInfo和xxxData的命名。
• 使用能读出来或能轻易用语言表达出来的命名。
• 使用可被搜索的名称。
• 避免使用编码，如使用匈牙利标记法（HN）、使用m_等成员前缀标明成员变量、使用标识标记是接口还是实现
• 代码不应当让读者产生思维映射或联想（P22，2.8，待举例说明或确认是否重复）。
• 类名和对象名应该是名词或名词短语，不应当是动词。
• 方法名应该是动词或动词短语。
• 不要起一些装可爱的命名。
• 给每个概念选一个词，全文以一贯之。
• 别使用双关语，一个词不应该有两个概念或意思。
• 使用解决方案领域名称，如使用CS术语、算法名、模式名、数学术语来协助命名。
• 使用源自所涉问题领域的名称（如果不能用平时熟知的术语命名，也请用所涉问题相关领域专业的名称命名）
• 为名称添加有意义的语境，如良好命名的类、函数、或名称空间内的名称就处于有意义的语境中。如果不这么做，可以给名称添加有语境的前缀。
• 不要添加没用的、多余的语境。若类、函数等中已经有语境相关的命名，则其中的名称没必要再添加多余的前缀标识语境。

函数

• 短小，再短小。
• 只做一件事。
• 每个函数应只有一个抽象等级。
• （建议）switch埋在抽象工厂下，只用于创建多态对象，多态类用接口约束。
• 函数使用描述性的名称。别害怕花时间和起长名称。
• 函数参数越少越好；
• 函数参数不要使用标识参数（布尔值）；
• 如果函数需要两个或以上的参数，其中一些参数应该被封装为类；
• 函数和参数的命名应能一起更好地解释函数的意图，以及参数的顺序和意图；
• 避免使用输出参数；
• 函数要么执行一个操作，要么回答一个问题，（函数应该只做一件事情）；
• 用异常而不是返回错误码，错误码处理会导致很多多余的错误处理逻辑代码；
  • 把try/catch代码块抽离到单独的处理逻辑或函数里，一大块逻辑被try/catch起来本身就很丑；
• 不写重复的代码；
• 结构化编程，别用goto语句；
• 总结：编程是另一形式的故事讲述，函数和类都是用于清晰和准确的帮助表达。

注释

• 尽量用代码去表达，然后才是注释
• 好的注释包括：
  • 规定的注释，像是代码的作者或者日期、copyright等；
  • 补充代码描述的基本信息注释；
  • 对作者意图的解释，像是为何有特殊排序，或者起了一个特殊数值的线程数；
  • 对难懂的变量或逻辑作阐述或解释；
  • 警告类注释，补充说明代码逻辑的执行后果；
  • 在开发初期使用 TODO 注释，后期删除；
  • 用注释放大一些不合理逻辑的重要性；
  • 写公共API的javadocs；
• 坏注释包括：
  • 自言自语的注释；
  • 多余或冗余的注释，注释需要描述清楚，不能把意思表达出来的注释就是多余的；
  • 误导性的注释；
  • 循规蹈矩的注释格式，如每个函数都加javadoc，或每个变量都加注释；
  • 日志式的注释；
  • 噪音注释，有些注释如标明函数是构造函数，或变量名本身已具备足够表达能力的附属注释，都是废话注释；
  • 位置标记注释，指的是类似"//Action /////////"的长串注释；
  • 括号后面的注释，如catch代码块后加“//catch”；
  • 代码的归属和署名注释没必要加，用代码版本管理完全可以追溯；
  • 注释掉的代码；
  • HTML注释；
  • 非本地注释或代码调试注释，如一些上下文环境中的端口号等注释；
  • 信息过多；
  • 注释和后面的代码无明显联系，或关联性不大，会导致读者阅读困难；
  • 函数头注释，作者认为短函数的签名注释是不需要的，但是在中文环境中英文代码不一定能完整地表达程序员的意思，译者认为每个函数或方法写个简单注释是利人利己的；

代码格式

• 暂不作参考。其实更多是不同开发团队的代码规范。

对象和数据结构

• 数据抽象，数据抽象指的是隐藏数据的本体，比如在vehicle类中定义方法[获取油箱容量(加仑)]和[获取现有油量(加仑)]是显示数据本体，隐藏本体的实现是定义方法[获取现存油量(百分比)]，在方法内用[现有油量]/[油箱容量]；数据本体是否要隐藏要视场景而定。
• Data/Object Anti-Symmetry，数据结构与对象反对称，面向对象是使用“对象”编程，面向过程是使用“数据结构”编程，反对称意思是面向过程和面向对象是相对的，面向过程编程容易添加新函数不影响已有数据结构，面向对象容易添加新类不影响已有函数。
• 迪米特原则（Law Of Demeter）
  • 详细地描述是，C类里的f方法只能调用以下对象的方法：
    1. C
    2. 被f创建的对象
    3. 被作为参数传进f方法的对象
    4. 由C的实体持有的对象
  • 火车失事，指的是列车式的调用不可取；作者认为一般最好将列车式的链式调用分散为一行一行的代码，但是即便如此，如果方法内的调用返回的是数据结构而不是类，内部结构被暴露，依然是不遵循Demeter原则。
  • 混杂导致了混合结构的出现，一半是对象，一半是数据结构，也是不好的。意思应该是一个类内行为和数据结构混杂在一起，该类既可以做某些事情，又可以不通过或通过setter方法更改类内的数据结构。这里作者没有描述这种混杂如何违反Demeter原则，描述得模模糊糊，难为读者。
  • 隐藏结构（这个和上面的混杂基本是在描述一个事情），一个对象不应该暴露其内部情形。一个对象要么做点什么事，要么用来传递点什么数据，不应暴露内部细节。
• 数据传输对象，就是一个类里没有任何动作函数，只是数据的载体。
• ActiveRecord，AR也是一种数据传输对象，作者认为不要把业务逻辑和AR操作混杂在一起。
• 总结，主要讲了对象和数据结构的区别和应用，当选择一种，就失去另外一种的好处。实际项目中应无偏见视情况而定。

异常处理

• 并未细看，主要是对异常处理的一些建议。

边界、单元测试、类、系统、迭进（emergence）、并发编程、逐步改进、JUnit、重构SerialDate、味道与启发

• 这些章节大致浏览了一遍，未感兴趣，后面需要再查阅。