[读书笔记]编写可维护软件的10大原则(Java版)

2020年06月30日 4313点热度 0人点赞 0条评论

为什么要写这个总结

  1. 并不是原文的简单复制, 而是记录对原则的思考。特别是对于自己项目的一些反思。
  2. 原文是Java版本, 有一些规则是否非常符合我当前主力语言Python来使用?记录我的一些相关思考
  3. 排版原因,原文的代码讲解其实看的并不是非常明白。希望通过电子档更清晰明白的展示出来。加深自己的理解,也方便其他人学习

适用其他语言?

这本书的绝大部分思想都是非常合适其他语言的。只不过可能需要根据具体情况具体分析。

比如原则4要求“参数个数<=4”. 这一点非常适用Java,但是对于Python其实有更好的解决方案,一些很著名的开源类库也没有这样做。

但是比如编写短小、简单的代码单元,需要注意重用而不是复制黏贴代码,这些原则放到其他语言都是非常合适的。

备注: 代码单元 (Unit of Code)

可独立维护或者执行的最小代码集合。在Java之中代码单元就是方法或者构造函数。

原则1:编写短小的代码单元

要点:

  1. 代码长度不超过15行
  2. 把超过15行长度的代码单元拆分到15行以内
  3. 动机:短小的代码容易理解、测试、重用

重构技巧1: 提取方法

原始代码:

重构1:把监控逻辑抽取出来

片段1

片段2

进一步重构:进一步拆分updateObservers

重构技巧2: 使用对象替代方法

原始代码:

👆上面这个方法一共18行,已经超过15行的标准。首先可以尝试把10~13行单独抽取成一个函数,比如

但是会发现,需要传入的参数太多,可以把整体重构成一个类BoardCreator

👆 上面这样重构的好处:

  1. 代码单元足够小
  2. 每个方法的入参个数也并没有很长

也是有代价的:

  1. 整体代码行数大大增加了 (上面代码已经被我忽略了一些,还比原来的长)
  2. 个人感觉:阅读的复杂度似乎并没有降低, 反而提高。对于使用者来说, 难度可能差不多

 

思考:

先不说Java,就我目前常用的Python而言, 15行的标准,感觉确实比较严格。

 

 

原则2: 编写简单的代码单元

要点:

  1. 限制每个代码单元的分支的数量 <= 4
  2. 复杂代码单元拆分成简单的代码单元
  3. 动机:简单的代码单元易于修改与测试

解释:

原始代码:

👆上面代码之中, 使用switch做条件判断,本身逻辑还是很清晰的。但是如果还需要不断的添加新的国家的时候,如果忘记写break语句,返回的结果就错误了。这种小bug其实反而是我们日常主要的bug。

如何重构呢?重构的方法比较多,书上推荐的做法:使用Map的数据结构

👆如上, 这样分支点的数量就不是线性增加, 而是常量2了。

书中还提到了可以定义一个Flag接口,然后各个国家的国旗实现这个接口的方法。 比如:

如果仅仅是针对这个例子, 我觉得这种方法不一定合适,因为这个数据结构很简单。 但是如果数据结构比较复杂, 我觉得这样才能体现出优势。

思考:

PS: 这个思考是个人的思考,并不是书上的内容。

1) 如果有的业务就是这样多的if-else分支。对其进行拆分也不能减小复杂度、或者减少分支点啊?

我想起之前同事展示的财务的相关代码。可能有20+个if-else分支。之前在做电商相关业务,计算物流费用的时候也遇到类似的场景。即使是在我们的API代码之中, 比如确定按照哪个维度进行Group就7~8个分支点。

是否有解决方案呢? 一个可能的方案拆分方法:拆分成两种。即:

  1. 按照属性维度(比如所属产品、日期)
  2. 按照广告指标维度(比如:所属账户、Campaign、Ad)进行聚合(Group)

2) 分支覆盖率的测试,我感觉重点还是分支条件之间是否独立

比如类似switch这种分支点, 大部分情况下可能还是可以忍受的。因为毕竟分支点是线性增加,而且条件之间相互应该是独立的。最难测试的是条件有先后顺序的情况

原则3:不写重复代码

要点:

  1. 不要复制代码
  2. 应该编写可重用的代码,或者调用已有的代码。
  3. 动机:bug只需要在一个地方修复。

重构方法

  1. 首先想到的是提取方法;但若是一个方法是另一个类的私有方法怎么办?
  2. 这时应当将提取的方法放到一个工具类中。
  3. 如果重复代码(6行以上完全相同)已不存在,但代码相似,具有相同的逻辑,这时应该考虑提取父类。

思考

1) 如何处理长文本?甚至需要对长文本做一些细微的调整?

比如有一些比较复杂的SQL,不同的SQL可能只是统计的指标或者Group的字段不太一样。这种情况跟具体使用的语言无关。比较好的方法:

  1. 提取方法,通过字符串追加或者参数变换的方式组装SQL
  2. 使用模板引擎进行SQL组装

如果使用Python进行SQL模板拼装的话, 可以尝试一下jinjasql这个类库。

原则4: 保持代码单元的接口简单

要点:

  • 限制每个代码单元的参数不超过4个
  • 应该将多个参数提取成对象
  • 动机:更容易理解与重用

举例:

上面的x,y,w,h是长方形的坐标与长宽。可以如下重构:

好处:在Java之中,如果多个参数一起传入,就需要很仔细的不要把参数位置弄混。特别是类型相同的情况之下。

对于Python就要好很多了,入参的时候可以指定关键字,这样即使参数位置调整了,在调用的时候也不需要很辛苦的修改调用代码。而且Python这种动态语言,编译的时候都无法检查出来。

比如我们项目之中一个拼接SQL的进行查询的函数。

↑ 主要分成好几组:

  • 时间
    • start_day / end_day
  • 过滤条件
    • filters_xxxx
  • group 条件
    • group_by_key
  • 其他:
    • by: 控制读取的是分天还是分时表
    • to_dollar: 控制最终是用人民币还是美元单位
    • limit: 每次多少条数据

调用方式:

这样就不会引起混乱了。

备注:这一条可能对Java比较适用,Python很多类库都有很长的参数列表,比如Pandas的read_excel函数:

原则5~7: 架构、组件松耦合

具体略

原则8:保持小规模代码库

要点:

  • 保持代码库规模尽可能小
  • 控制代码库增长,主动减少系统代码体积
  • 动机:拥有小型代码库是成功的因素之一

动机

  1. 大型代码库容易失败
  2. 大型代码库更加难以维护
  3. 大型系统会出现更密集的缺陷

如何执行?

功能层面:

  • 控制需求蔓延:不要做无用的需求
  • 功能标准化:将相似而又略有区别的功能合并,提供复用程度

技术层面:

  • 不要复制代码
  • 重构已有代码:
    • 重新梳理代码、简化结构、删除代码冗余以及重用度
    • 也有仅仅删除一些无用的过期的功能
  • 使用第三方库和框架:
    • 不要重复造轮子
    • 也不要去改造轮子(除非你的改造被合并到开源类库之中)

原则9:自动化开发部署和测试

要点:

  • 对你的代码进行自动化测试
  • 通过测试框架编写自动化测试
  • 动机:大大降低风险

感触

想说爱你不容易

备注:

原文标题:Automated Tests 。即仅仅是自动化测试。

原则10:编写简洁的代码

要点:

  • 编写简洁的代码
  • 不要留下坏味道
  • 动机:简洁的代码才是可维护的代码

7条开发人员“童子军军规”

  1. 不要编写单元级别的代码坏味道。
    1. 具体参考前面几个原则
  2. 不要编写不好的注释
    1. 看了书上举的例子也不是很明白。但是力求简明清晰
  3. 不要注释代码。
    1. 比如有一段代码不用了,不要通过注释掉来保留而是应该彻底删除。因为Git/SVN都能恢复回来
  4. 不要保留废弃代码。
    1. 方法中无法到达的代码
    2. 无用的私有方法
    3. 注释中的方法
  5. 不要使用过长的标识符名称。
    1. 名言:计算机科学中只有两个难题:缓存失效和命名
    2. Bad Example: GlobalProjectNamingStrategyConfiguration
  6. 不要使用魔术常量。
  7. 不要使用未正确处理的异常。推荐做法:
    1. 捕获一切异常:记录系统所有失败的行为并加以改进
    2. 捕获特定的异常:
      1. 为了追踪某些特定事件,就应该单独捕获特定的异常
      2. 不要直接Throwable、 Exception、RuntimeException
    3. 展示给终端用户之前,先将特定异常信息转成通用信息。
      1. 终端用户完全看不懂
      2. 也不安全:提供了过多的内部信息

感触

这一条我感觉放在最后是最合适的,因为这一条才是最难最难的。

这个需要开发人员的经验积累,培养良好的习惯,跟自己的懒惰作斗争。

脑图

图片来源:https://zhuanlan.zhihu.com/p/81777441

参考资料:

RangerWolf

保持饥渴的专注,追求最佳的品质

文章评论