为什么要写这个总结
- 并不是原文的简单复制, 而是记录对原则的思考。特别是对于自己项目的一些反思。
- 原文是Java版本, 有一些规则是否非常符合我当前主力语言Python来使用?记录我的一些相关思考
- 排版原因,原文的代码讲解其实看的并不是非常明白。希望通过电子档更清晰明白的展示出来。加深自己的理解,也方便其他人学习
适用其他语言?
这本书的绝大部分思想都是非常合适其他语言的。只不过可能需要根据具体情况具体分析。
比如原则4要求“参数个数<=4”. 这一点非常适用Java,但是对于Python其实有更好的解决方案,一些很著名的开源类库也没有这样做。
但是比如编写短小、简单的代码单元,需要注意重用而不是复制黏贴代码,这些原则放到其他语言都是非常合适的。
备注: 代码单元 (Unit of Code)
可独立维护或者执行的最小代码集合。在Java之中代码单元就是方法或者构造函数。
原则1:编写短小的代码单元
要点:
- 代码长度 不超过15行
- 把超过15行长度的代码单元 拆分到15行以内
- 动机:短小的代码 容易理解、测试、重用
重构技巧1: 提取方法
原始代码:
public void start() { if (inProgress) { return; } inProgress = true; // Update observers if player died: if (!isAnyPlayerAlive()) { for (LevelObserver o: observers) { o.levelLost(); } } // Update observers if all pellets eaten: if (remainingPellets() == 0) { for (LevelObserver o: observers) { o.levelWon(); } } }
重构1:把监控逻辑抽取出来
片段1
public void start() {
if (inProgress) {
return;
}
inProgress = true;
updateObservers(); // 被重构抽取出来的函数
}
片段2
private void updateObservers() { // Update observers if player died: if (!isAnyPlayerAlive()) { for (LevelObserver o: observers) { o.levelLost(); } } // Update observers if all pellets eaten: if (remainingPellets() == 0) { for (LevelObserver o: observers) { o.levelWon(); } } }
进一步重构:进一步拆分 updateObservers
private void updateObservers() { // 被拆成了两个函数 updateObserversPlayerDied(); updateObserversPelletsEaten(); } private void updateObserversPlayerDied() { if (!isAnyPlayerAlive()) { for (LevelObserver o: observers) { o.levelLost(); } } } private void updateObserversPelletsEaten() { if (remainingPellets() == 0) { for (LevelObserver o: observers) { o.levelWon(); } } }
重构技巧2: 使用对象替代方法
原始代码:
public Board createBoard(Square[][] grid) {
assert grid != null;
Board board = new Board(grid);
int width = board.getWidth();
int height = board.getHeight();
for (int x = 0; x < width; x++) {
for (int y = 0; y < height; y++) {
Square square = grid[x][y];
for (Direction dir: Direction.values()) {
int dirX = (width + x + dir.getDeltaX()) % width;
int dirY = (height + y + dir.getDeltaY()) % height;
Square neighbour = grid[dirX][dirY];
square.link(neighbour, dir);
}
}
}
return board;
}
:point_up_2:上面这个方法一共18行,已经超过15行的标准。首先可以尝试把 10~13
行单独抽取成一个函数,比如
public voide setLink(){
// skip
}
但是会发现,需要传入的参数太多,可以把整体重构成一个类 BoardCreator
class BoardCreator { private Square[][] grid; private Board board; private int width; private int height; BoardCreator(Square[][] grid) { // init ... } Board create() { for (int x = 0; x < width; x++) { for (int y = 0; y < height; y++) { Square square = grid[x][y]; for (Direction dir: Direction.values()) { setLink(square, dir, x, y); } } } return this.board; } private void setLink(Square square, Direction dir, int x, int y) { // ... } }
:point_up_2: 上面这样重构的好处:
- 代码单元足够小
- 每个方法的入参个数也并没有很长
但也是有代价的:
- 整体代码行数大大增加了 (上面代码已经被我忽略了一些,还比原来的长)
- 个人感觉:阅读的复杂度似乎并没有降低, 反而提高。对于使用者来说, 难度可能差不多
原则2: 编写简单的代码单元
要点:
- 限制每个代码单元的分支的数量 <= 4
- 复杂代码单元拆分成简单的代码单元
- 动机:简单的代码单元易于修改与测试
解释:
原始代码:
public List < Color > getFlagColors(Nationality nationality) {
List < Color > result;
switch (nationality) {
case DUTCH:
result = Arrays.asList(Color.RED, Color.WHITE, Color.BLUE);
break;
case GERMAN:
result = Arrays.asList(Color.BLACK, Color.RED, Color.YELLOW);
break;
case BELGIAN:
result = Arrays.asList(Color.BLACK, Color.YELLOW, Color.RED);
break;
case FRENCH:
result = Arrays.asList(Color.BLUE, Color.WHITE, Color.RED);
break;
case ITALIAN:
result = Arrays.asList(Color.GREEN, Color.WHITE, Color.RED);
break;
case UNCLASSIFIED:
default:
result = Arrays.asList(Color.GRAY);
break;
}
return result;
}
:point_up_2:上面代码之中, 使用 switch
做条件判断,本身逻辑还是很清晰的。但是如果还需要不断的添加新的国家的时候,如果忘记写 break
语句,返回的结果就错误了。这种小bug其实反而是我们日常主要的bug。
如何重构呢?重构的方法比较多,书上推荐的做法: 使用Map的数据结构 。
private static Map < Nationality, List < Color >> FLAGS =
new HashMap < Nationality, List < Color >> ();
static {
FLAGS.put(DUTCH, Arrays.asList(Color.RED, Color.WHITE, Color.BLUE));
FLAGS.put(GERMAN, Arrays.asList(Color.BLACK, Color.RED, Color.YELLOW));
FLAGS.put(BELGIAN, Arrays.asList(Color.BLACK, Color.YELLOW, Color.RED));
FLAGS.put(FRENCH, Arrays.asList(Color.BLUE, Color.WHITE, Color.RED));
FLAGS.put(ITALIAN, Arrays.asList(Color.GREEN, Color.WHITE, Color.RED));
}
public List < Color > getFlagColors(Nationality nationality) {
List < Color > colors = FLAGS.get(nationality);
return colors != null ? colors : Arrays.asList(Color.GRAY);
}
:point_up_2:如上, 这样分支点的数量就不是线性增加, 而是常量 2
了。
书中还提到了可以定义一个 Flag
接口,然后各个国家的国旗实现这个接口的方法。 比如:
public interface Flag { List < Color > getColors(); } public class DutchFlag implements Flag { public List < Color > getColors() { return Arrays.asList(Color.RED, Color.WHITE, Color.BLUE); } }
如果仅仅是针对这个例子, 我觉得这种方法不一定合适,因为这个数据结构很简单。 但是如果数据结构比较复杂, 我觉得这样才能体现出优势。
思考:
PS: 这个思考是个人的思考,并不是书上的内容。
1) 如果有的业务就是这样多的 if-else
分支。对其进行拆分也不能减小复杂度、或者减少分支点啊?
我想起之前同事展示的财务的相关代码。可能有20+个 if-else
分支。之前在做电商相关业务,计算物流费用的时候也遇到类似的场景。即使是在我们的API代码之中, 比如确定按照哪个维度进行Group就7~8个分支点。
是否有解决方案呢? 一个可能的方案拆分方法:拆分成两种。即:
2) 分支覆盖率的测试,我感觉重点还是分支条件之间是否独立
比如类似 switch
这种分支点, 大部分情况下可能还是可以忍受的。因为毕竟分支点是线性增加,而且条件之间相互应该是独立的。 最难测试的是条件有先后顺序的情况 。
原则3:不写重复代码
要点:
- 不要复制代码
- 应该编写可重用的代码,或者调用已有的代码。
- 动机:bug只需要在一个地方修复。
重构方法
- 首先想到的是提取方法;但若是一个方法是另一个类的私有方法怎么办?
- 这时应当将提取的方法放到一个工具类中。
- 如果重复代码(6行以上完全相同)已不存在,但代码相似,具有相同的逻辑,这时应该考虑提取父类。
思考
1) 如何处理长文本?甚至需要对长文本做一些细微的调整?
比如有一些比较复杂的SQL,不同的SQL可能只是统计的指标或者Group的字段不太一样。这种情况跟具体使用的语言无关。比较好的方法:
- 提取方法,通过字符串追加或者参数变换的方式组装SQL
- 使用模板引擎进行SQL组装
如果使用Python进行SQL模板拼装的话, 可以尝试一下 jinjasql
这个类库。
原则4: 保持代码单元的接口简单
要点:
- 限制每个代码单元的 参数不超过4个
- 应该将 多个参数提取成对象
- 动机:更容易理解与重用
举例:
private voide render(int x, int y, int w, int h) { // skip }
上面的 x,y,w,h
是长方形的坐标与长宽。可以如下重构:
public class Rectangle{ // skip } private voide render(Rectangle) { // skip }
好处:在Java之中,如果多个参数一起传入,就需要很仔细的不要把参数位置弄混。特别是类型相同的情况之下。
对于Python就要好很多了,入参的时候可以指定关键字,这样即使参数位置调整了,在调用的时候也不需要很辛苦的修改调用代码。而且Python这种动态语言,编译的时候都无法检查出来。
比如我们项目之中一个拼接SQL的进行查询的函数。
def read_toutiao_performance_stat_report(
start_day, end_day,
filters_source=None, group_by_key=None,
filters_bu=None, filters_app=None, filters_account=None,
filters_campaign_id=None,
filters_geo=None, filters_adset_id=None, by="daily", to_dollar=False,
limit=None):
pass
↑ 主要分成好几组:
- 时间
- start_day / end_day
- 过滤条件
- filters_xxxx
- group 条件
- group_by_key
- 其他:
- by: 控制读取的是分天还是分时表
- to_dollar: 控制最终是用人民币还是美元单位
- limit: 每次多少条数据
调用方式:
dataset = fetch_report( start_day, end_day, filters_source=None, group_by_key=group_by_key, filters_bu=filters_bu, filters_app=filters_app, filters_account=filters_account, filters_campaign_id=filters_campaign_id, filters_adset_id=filters_adset_id, filters_geo=filters_geo, by=by, to_dollar=to_dollar, limit=limit)
这样就不会引起混乱了。
备注:这一条可能对Java比较适用,Python很多类库都有很长的参数列表,比如Pandas的 read_excel
函数:
def read_excel(
io,
sheet_name=0,
header=0,
names=None,
index_col=None,
usecols=None,
squeeze=False,
dtype=None,
engine=None,
converters=None,
true_values=None,
false_values=None,
skiprows=None,
nrows=None,
na_values=None,
keep_default_na=True,
verbose=False,
parse_dates=False,
date_parser=None,
thousands=None,
comment=None,
skipfooter=0,
convert_float=True,
mangle_dupe_cols=True,
**kwds,
):
pass
原则5~7: 架构、组件松耦合
具体略
原则8:保持小规模代码库
要点:
- 保持代码库规模尽可能小
- 控制代码库增长,主动减少系统代码体积
- 动机: 拥有小型代码库是成功的因素之一
动机
- 大型代码库容易失败
- 大型代码库更加难以维护
- 大型系统会出现更密集的缺陷
如何执行?
功能层面:
- 控制需求蔓延:不要做无用的需求
- 功能标准化:将相似而又略有区别的功能合并,提供复用程度
技术层面:
- 不要复制代码
- 重构已有代码:
- 重新梳理代码、简化结构、删除代码冗余以及重用度
- 也有仅仅删除一些无用的过期的功能
- 使用第三方库和框架:
- 不要重复造轮子
- 也不要去改造轮子(除非你的改造被合并到开源类库之中)
原则9:自动化开发部署和测试
要点:
- 对你的代码进行自动化测试
- 通过测试框架编写自动化测试
- 动机:大大降低风险
感触
想说爱你不容易
备注:
原文标题:Automated Tests 。即仅仅是自动化测试。
原则10:编写简洁的代码
要点:
- 编写简洁的代码
- 不要留下坏味道
- 动机:简洁的代码才是可维护的代码
7条开发人员“童子军军规”
- 不要编写单元级别的代码坏味道。
- 具体参考前面几个原则
- 不要编写不好的注释
- 看了书上举的例子也不是很明白。但是力求简明清晰
- 不要注释代码。
- 比如有一段代码不用了,不要通过注释掉来保留而是应该彻底删除。因为Git/SVN都能恢复回来
- 不要保留废弃代码。
- 方法中无法到达的代码
- 无用的私有方法
- 注释中的方法
- 不要使用过长的标识符名称。
GlobalProjectNamingStrategyConfiguration
- 不要使用魔术常量。
- 不要使用未正确处理的异常。推荐做法:
- 捕获一切异常:记录系统所有失败的行为并加以改进
- 捕获特定的异常:
- 为了追踪某些特定事件,就应该单独捕获特定的异常
- 不要直接Throwable、 Exception、RuntimeException
- 展示给终端用户之前,先将特定异常信息转成通用信息。
- 终端用户完全看不懂
- 也不安全:提供了过多的内部信息
感触
这一条我感觉放在最后是最合适的,因为这一条才是最难最难的。
这个需要开发人员的经验积累,培养良好的习惯,跟自己的懒惰作斗争。
脑图
图片来源:https://zhuanlan.zhihu.com/p/81777441
参考资料:
原文
https://www.flyml.net/2020/06/30/building-maitainable-software-java/
本站部分文章源于互联网,本着传播知识、有益学习和研究的目的进行的转载,为网友免费提供。如有著作权人或出版方提出异议,本站将立即删除。如果您对文章转载有任何疑问请告之我们,以便我们及时纠正。PS:推荐一个微信公众号: askHarries 或者qq群:474807195,里面会分享一些资深架构师录制的视频录像:有Spring,MyBatis,Netty源码分析,高并发、高性能、分布式、微服务架构的原理,JVM性能优化这些成为架构师必备的知识体系。还能领取免费的学习资源,目前受益良多

转载请注明原文出处:Harries Blog™ » [读书笔记]编写可维护软件的10大原则(Java版)