来源书籍

代码整洁之道

Skill 版本:v24 经典原理 331 张卡片

Robert C. Martin · 韩磊 译 · 人民邮电出版社 · 2010-01-01 · 第1版 · ISBN 978-7-115-21687-8

全书导读

本书以代码的可读、可改与持续照料为主线。中文版权页记2010年1月第1版,与OPF日期一致,原书名为Clean Code: A Handbook of Agile Software Craftsmanship;主作者Robert C. Martin,具体章节另有合写或署名贡献者。这里沿用现有《代码整洁之道》身份,不与同主题书合并。

阅读分三部分:先认识命名、函数、对象与边界等原则,再在Args、JUnit和SerialDate案例中观察每次变换的理由,最后将味道与启发回连案例。附录A补充并发机制,附录B保留SerialDate源代码,均列入完整阅读。代码与书面测试输出用于分析,尚无本机运行或测试结论。

全书主线

全书把代码质量看成持续修改时的理解成本。可运行只说明某些行为发生了,维护者还需要看懂对象是什么、操作改变了什么、错误如何传播。命名、函数和注释先改善局部表达;格式、对象与数据、错误处理和第三方边界再决定这些局部怎样协作。小函数和少参数是作者偏好的手段,仍要以职责与实际复杂度判断,不把行数当作质量证明。

测试给修改提供可重复的行为判据。类和系统设计围绕变化理由划定责任,简单设计再要求在测试约束下消除重复、表达意图。并发则让问题超出单线程阅读:多个步骤即使各自安全,组合仍可能破坏共享状态,阻塞和资源依赖还会带来活性问题。附录A把这些约束展开,避免把清晰命名误当并发正确的保证。

Args、JUnit比较消息和SerialDate三个案例展示原则如何在实际变换中接受检验。Args反复分离解析责任与错误信息;JUnit围绕差异片段和上下文重组分析与合成;SerialDate则检验日期值、枚举、区间和创建策略的边界。它们包含试错、中间版本及已识别的教材错误,说明重构并不总是单向前进。第17章的味道是重新查找问题的线索,附录B使日期案例可回到完整源码核对,结束语再把讨论收束到日常职业承诺。

flowchart TD
 A[修改需要理解既有行为] --> B[名称 函数 注释表达意图]
 B --> C[对象 错误 边界组织协作]
 C --> D[测试约束行为与反馈]
 D --> E[类 系统 简单设计应对变化]
 E --> F[案例中逐步变换并核对契约]
 F --> B
 G[并发与资源约束] --> C
 G --> D
 H[启发与源码附录] --> F

图说明各部分如何相互提供判断依据,不表示每个项目都按固定顺序完成设计。

内容提要

内容提要用代码质量、整洁度与后期维护建立本书定位,并说明规则配正反案例的写法及读者。它是正文路线介绍,未独立论证“成正比”的数量关系,故不把宣传表述转成数学规律。具体机制由后续章节展开。

序

整体结构决定系统怎样分工,局部代码的命名、边界和错误处理决定人怎样理解与修改这种结构。宏观规划不能替代日常照料,局部整齐也不能证明架构适合业务。门把手与建筑的例子是层次互补的类比,不是“只要格式好就不需设计”的结论。 详见细节与架构共同影响维护。

5S把工作整理成可持续的日常纪律:整理用于辨认并命名所需事物,整顿使代码出现在可预期的位置,清扫移除遗留杂物,清洁形成共同标准,素养使成员持续贯彻和改进。序言将工作场所管理类比到代码维护,不是把制造业历史直接当软件效果实验;原译“清楚”“身美”须结合其解释理解。 详见五常管理可映射代码纪律。

等缺陷显现才处理,会把维护拖成被动抢修;日常检查、小步重构与一开始选择易读易改结构,可让后续修改更有落点。维护准备应进入开发过程,而不是产品发布后的附属工作。机械换油和按年重做模块只是序言类比与建议,不应机械转换为所有软件的固定重写周期。 详见易维护性要在设计时准备。

设计不只发生在新模块出现之前,也发生在整理现有接口、替换实现和改善局部结构时。把一次改动视作有目标的局部修复,才能同时考虑眼前问题与它对周围结构的影响。持续设计不是允许无边界地改整个项目;修复范围与行为保持仍需清楚。 详见局部修复也是持续设计。

观察到统一缩进与较低缺陷同时出现,只能提出两者有关的线索,不能证明单独改变缩进就必然减少缺陷。序言自己称该发现“不太严密”,也未给出样本和控制条件。团队纪律、审查或其他实践可能共同影响两者;统一风格有沟通用途,但不要把该轶事当作量化因果实验。 详见缩进相关不等于缺陷因果。

模块怎样调用、职责如何分开以及数据被谁持有,都最终落实在代码中。因此代码变换可能是在改善设计,而不只是返工生产同一件物品。图和架构说明能帮助沟通,但需要与实际耦合、内聚及接口相对应;把代码当设计不等于否认必要的规划或文档。 详见代码也是设计的载体。

团队需要知道当前代码还存在哪些混乱和未完成条件,才能安排真实的修复与交付。把必要清理纳入完成标准,并在修改时留下小幅改善,可减少“已完成”掩盖后续负担。诚实不是声称代码已经完美,也不等于每次提交都应无限重构;应说明做到什么、仍缺什么及其影响。 详见如实暴露代码状态才能改进。

原书依据 · 8 处

关于封面

这一项解释封面图像,并穿插科幻电影联想和作者对星系的个人猜想。图像说明帮助理解封面创作背景,不是软件设计论证;此处没有把未经核验的天文数字、爆炸或黑洞猜想转成知识卡。

代码猴子与童子军军规

译者说明从演讲到接受翻译的缘起,并概括规则、代码感与三个重构案例的阅读价值。它承接序言的日常照料,再引向前言的知行结合。已在相关讲解中保留这两条思想,因此不为译序复述重复生成卡;人物经历、腕带故事和联系方式按出版背景理解。

前言

编程规则只有连回输入、约束、代码变化及其后果,才有助于形成判断。读案例时先看原实现的问题,再解释为何选择这一步变换、改善了什么及还有什么代价;最后回到规则清单检验适用条件。只背“函数要小”等口号不能代替实践,阅读成功也不是本机行为验证;本书的三部分安排正用于让原则与具体决策互相解释。 详见学习规则要追踪具体决策。

原书依据 · 2 处

第1章 整洁代码

本章把整洁代码从外观偏好转成维护问题:读懂、修改和交付为什么会受代码结构影响,为什么一次能运行不足以证明长期可维护。随后汇集多位实践者的定义,分别强调责任、表达、可增补、测试和小型抽象,最后用作者/读者与童子军军规把这些要求放进日常修改。它建立后续命名、函数及案例分析的判断起点,而非给出一张按分数计算优劣的唯一表。

细节照料延续序言的细节与架构共同影响维护;章节末尾也回到前言的学习规则要追踪具体决策。两处补充位置对应真实原文,具体主讲解仍保留在原章节。

把需求交给机器执行时,系统最终必须对输入、条件和结果作足够明确的选择。更高层语言、领域语言或生成工具可以减少手工细节,却不能让含糊要求自动成为唯一正确的行为。这里保留的是可执行语义需要明确这一约束,不把本书“代码永不消失”的说法当作对未来工具或职业的已验证预测。 详见自动化仍需明确执行语义。

一次执行成功只说明某条路径产生了结果,不说明后来的人能理解、修改或持续交付它。赶工遗留的混乱会把判断改动影响的工作推给下一次任务。匿名公司衰败是作者回忆的警示案例,没有可核验样本或对照,不能据此断言所有公司失败都由代码造成;改进应围绕真实维护成本和行为证据。 详见可运行不等于可持续维护。

当一处改动依赖很多隐藏关系,开发者须先理解多处代码才能安全下手;新增成员又需要学习这些关系。进度压力下继续增加不清楚的修改,可能让理解和协调负担进一步扩大。生产力曲线是作者的示意,未给出实测数据;人员增加也有不同效果,不能从该图推出所有团队生产力必然趋零。 详见混乱会放大修改的理解负担。

另起新系统时,团队不仅要补齐旧功能,还得跟上旧系统仍在发生的业务变化。若完成标准不断移动,替换可能长期无法收束,新代码也会经历人员流动和维护压力。重写不是天然错误,但需要明确替换边界、可验证的阶段与双轨成本;本章故事说明风险,不证明所有重写都失败或局部重构永远最佳。 详见整体重写需追赶现有系统变化。

掌握实现细节的人应把混乱、变更影响和必要质量工作告知决策者,让进度承诺依据真实条件。经理负责业务与时间压力,开发者仍需解释实现风险并提出可讨论的取舍。专业责任不意味着个人能决定全部资源,也不保证提出异议没有组织代价;本章医生类比用来强调沟通立场,不构成医疗或法律建议。 详见风险沟通属于开发责任。

看出代码难读,是对现状的判断;知道先改哪里、用什么变换和怎样保持行为,才是可执行的改进能力。需要把诊断联系到命名、拆分、消重等具体选择,并观察它们对上下文的影响。代码感可作为这种熟练判断的简称,不是凭审美直觉就能免除测试和约束说明。 详见辨认缺陷与安排变换不同。

一个函数、类或模块若同时承担互不相关的目标,读者需要切换多套理由才能理解它,也容易在修改一项行为时影响另一项。围绕清楚目的组织实现,可减少这种混合。只做一件事需要按责任与抽象层解释,不能机械等同一行代码、一个方法或禁止一项业务由多个步骤完成。 详见集中责任有助于表达意图。

读者应能从抽象名称和控制结构看出程序在处理什么、为何走向下一步,而不必拼凑散落线索猜意图。简洁不是省略必要信息;抽象若隐藏理解行为所需的条件,仍会增加猜测。散文比喻强调可理解的展开,不要求代码像自然语言一样任意含糊。 详见直接控制流让设计意图可读。

读懂当前行为,不等于能在清楚的边界内增加功能。可增补还依赖明确接口、可替换的实现和保护既有行为的证据;读者应能判断改动放在哪里及会影响什么。二者相互帮助,却不能仅凭命名流畅就证明新功能容易、安全或无需测试。 详见可读与可增补是不同能力。

单元与验收测试可把重要输入和预期结果保存下来,使后续改动能检查是否破坏这些约束。它们与可读性互补:代码易懂帮助分析,测试帮助观察已编码的行为。测试缺失增加不确定性,但测试存在或全通过仍不证明覆盖了全部需求;本章“没有测试不干净”是作者规范主张,不是完备性定理。 详见测试为修改提供行为约束。

向外暴露的入口越多,使用者越需辨别差异,维护者也越需兼顾已有调用。用清楚且必要的接口表达同一职责,可减少无意义的选择与耦合。少不是任意合并不同责任,也不是禁止合理重载;数量取舍要以能否准确表达需求、保持兼容及支持使用为依据。 详见少量明确接口降低依赖负担。

简单设计先要求通过应有测试,再消除重复、表达设计意图,最后才考虑减少类和方法等实体。这个顺序避免为凑最少结构破坏行为或把多个意图挤在一起。通过全部现有测试仍只约束已写出的要求,实体少也不是独立的质量分数;冲突时先说明要保护的行为与表达。 详见简单设计规则有优先顺序。

相同处理在多处重复,可能意味着一个共同想法尚未被命名并放到合适位置。先判断这些代码是否代表同一规则,再提取可共用表达,能避免同一规则改动时多处漂移。文本相似不必然同一业务责任,不应为了消除所有相似片段制造难懂的通用层。 详见重复可能暴露未表达的概念。

当调用者实际只需要“按条件找一项”,可让它依赖这个查找接口,把哈希表或其他集合方案留在内部。这样替换实现时,调用者不必跟着操作存储细节;接口仍需定义未找到、重复或顺序等与任务有关的语义。先用简单实现,抽象用于隔离已知变化,不是提前加入所有可能的框架。 详见小型抽象隔离查找实现。

名称、抽象层次和控制流若沿着使用者的问题展开,读者就能预期下一段负责什么,减少在系统里追逐碎片。可预期来自一致而明确的行为契约,不只是语句看起来顺口。程序仍须处理异常和少见条件,应让这些分支可见,而不是为追求“毫不惊讶”隐藏失败。 详见接口应使下一步行为可预期。

一组长期实践形成的规则可以作为训练起点,但它仍代表特定背景与取舍。学习时先理解规则要解决的问题,再用代码和约束判断何时采用、何时调整,也可向其他方法学习。经验丰富或表达坚决都不等于最终权威,反对一条规则也应说明具体理由,而不是只换另一句口号。 详见规则流派需要按约束检验。

修改代码通常需要先查看调用、初始化及周边实现,理解成本会进入每次修改的成本。命名和组织应让后来的人更容易取得必要上下文,即使初次写作多花一些时间。编辑器回放和读写10:1是作者的观察说明,未给可推广样本;它提示关注阅读,不构成所有任务固定比例或必须无限整理的标准。 详见为读者降低修改前的理解成本。

完成一次任务时,顺手让相关代码比开始时清楚一点,例如改正一个误导名称、拆开过长函数或移除重复,可把维护分散到日常工作中。范围应与当前改动和可验证行为相称,避免把小任务扩大为无边界重写。童子军军规是持续照料的实践提醒,不保证每次表面清理都必然降低缺陷。 详见每次修改留下局部改善。

原书依据 · 35 处

第2章 有意义的命名

第1章说明为什么可读与可改值得维护,本章把目标落到每天接触的名称。名字先要指向真实对象和角色,再通过发音、搜索、类型线索、共同词汇及语境降低理解负担。不同名称应说明不同含义,同一概念则尽量稳定表达;类、函数或命名空间提供的背景可以减少重复前缀。最后用地址和消息对象说明:要增加的是有意义的语境,而不是尽可能多的字母。

elapsedTimeInDays不仅表示一个整数,还说明量的是经过时间、单位是天。好的名称让调用处看出对象为何存在、记录什么或执行什么,减少依赖外部注释猜含义。单位也可由明确类型和接口统一表达,不必在每个名字重复全部背景;名称仍应与实际计算和存储约定相符。 详见名称同时说明对象与单位。

扫雷例从theList、x[0]==4改为gameBoard、STATUS_VALUE和FLAGGED后,运算与嵌套几乎没变,读者却能看出是在选已标记格。改名的收益是补足缺失的领域上下文,不是减少执行步骤或已经证明性能提升。筛选条件与常量仍须真实对应数据含义。 详见领域命名能显露筛选意图。

cell.isFlagged()把“已标记吗”的领域问题交给单元格对象,调用方不再读取固定数组下标和魔术数。这样可让状态存储方式留在对象内部,调用者只依赖判断含义。隐藏不等于消除状态或自动验证它;接口仍需规定怎样判真,不能只换一个好听方法名就认为数据模型正确。 详见行为接口可隐藏状态表示。

accounts若只是一些账号,名称就不应让人误以为具有某种列表顺序或接口。类型词、平台缩写和领域词都可能给读者既有暗示,应检查它是否符合真实用途。即使底层确是List,也常可用任务语义替代具体容器名;规则关注误导,而不是必须把实现类型编码进名称。 详见名称不应暗示不存在的能力。

只有中间几个字母不同的长名称,或l、O与1、0混用,会让人选错变量或接口。应让区别落在清楚的角色词上,而不是要求后来者记住特殊字体。名称在常用编辑器与检索结果中都应容易辨认;这解决辨别成本,不代替功能和类型检查。 详见视觉差异也影响名称辨别。

copyChars的source/destination说明谁提供数据、谁被写入,比a1/a2更能揭示调用责任。类似CustomerInfo与Customer若没有清楚约定,只是制造多个看似可选的名字。Info、Data等词并非天然无意义;只有当它们确实标识不同层次或内容时才值得保留,不能为通过重名限制随意加字。 详见不同名称应说明不同角色。

generationTimestamp可直接与口头“生成时间戳”对应,genymdhms则需要同事学习自造读法。名称在评审、求助和新人解释中也要使用,应优先用团队能说清并理解的词。这里依据协作成本,不将原文有关脑部和进化的笼统说法当神经科学证据。 详见可读出的名字便于协作讨论。

跨多处使用的数量或规则,用有含义的名字比散落的7或e更容易定位和核对。短循环中的i可由局部上下文解释,作用域扩大时则应增加辨识信息。名称长度取决于查找和理解需要,不是越长越好;工具的符号搜索有帮助,但名字仍要让结果可辨。 详见可搜索性应匹配名称作用域。

PhoneNumber phoneString把旧表示写进名字,类型改成领域对象后后缀仍可能留下错误线索。若类型系统和局部定义已提供所需信息,再重复编码会增加同步维护负担。编码在某些协议或团队约定下仍可有作用,判断应看它表达了什么且能否保持一致,不接受原文“早期C编译器不做类型检查”的笼统历史说明。 详见类型编码可能落后于真实类型。

小类中的description及显式this.description,可让读者区分字段与参数,不一定需要m_dsc这样的额外编码。前缀是否保留应结合语言、代码规模和一致约定,不能因为某个IDE能高亮就假定所有读者都在同一环境。目标是清楚表达成员责任,压缩dsc等缩写反而可能增添解码。 详见成员身份可由局部语境表达。

ShapeFactory让调用者知道“创建形状的入口”,而不是先理解它究竟由接口还是哪种具体类实现。若必须区分多个实现,可在实现名字中说明差异。I前缀是否有用取决于现有语言与团队约定;职责清楚比无条件反对某个字母重要,也不应为改风格破坏既有公共名称。 详见公开接口名称优先表达角色。

若读者必须记住r代表某种去主机名的小写URL,阅读会多出一次从暗号到真实概念的转换。选团队熟悉且直接指向所处理对象的名字,可把注意力留给逻辑。i、j等短作用域惯例可有共同理解,不应为了消灭所有缩写而制造冗长重复;衡量的是读者需要额外记多少规则。 详见名字应减少额外的心智翻译。

类名通常以名词或名词短语说明它代表的事物或服务,如Customer或AddressParser。Manager、Processor等泛词若不说明管理什么和负责哪一层,仍会隐藏责任;有明确领域含义时它们也可使用。词性只是阅读线索,不能仅从类名是名词就证明职责内聚。 详见类名应显露对象承担的角色。

执行动作的方法可用postPayment、save等动作词;询问状态的isPosted则应只陈述是否已入账这一事实。命名之前先确认方法负责查询、修改还是创建,结果应描述该责任的业务结果。不要为迎合调用方分支而把动作结果命名成“是否跳过”,也不能用get外观隐藏额外修改;具体前缀仍应遵守所处接口约定。 详见方法名称应对应实际业务责任。

Complex.FromRealNumber(23.0)比单看new Complex(23.0)更容易辨认数字代表什么。静态工厂把创建意图放到调用处,也可在需要时配合非公开构造器统一入口。它仍应返回符合名称的对象,不能只因叫工厂就推定有缓存、单例或额外校验;这里的收益是语义表达,不是性能结论。 详见命名工厂能说明构造参数含义。

HolyHandGrenade或某句俚语需要读者记得典故才能猜到删除/终止行为。面向多人长期维护时,用DeleteItems、abort等任务词可减少这层依赖。幽默本身不是错误,问题是关键语义是否只能靠笑话解码;名称应在不了解作者故事时仍能说明操作。 详见笑话名称会增加文化依赖。

若fetch、retrieve、get在多个类中其实表达同一取值责任,混用会迫使调用者记住作者或模块偏好。共同词汇让名称形成可预期模式。若返回、状态变化或错误语义确实不同,应保留有意义区别;一致是同一概念用同一词,不是所有方法统一前缀就完成设计。 详见同一概念宜保持词汇一致。

若某处add计算两个值的新结果,另一处却把元素放入已有容器,应让调用者看清结果和副作用的不同。可用append、insert等更具体词,或遵守既有API中清楚定义的add契约。书中例子是命名建议,不意味着Java集合等现有协议中的add应一律改名;要比较实际责任,而非单按拼写认定等价。 详见相同词不应掩盖不同操作。

实现算法、队列或模式时,可用协作者熟悉的技术术语;表达业务规则时,应保留领域专家使用的概念。先辨认代码处理的是技术机制还是业务对象,避免把两者混成暗号。程序员并非天然知道所有术语,业务读者也可能参与评审;共同理解需要在边界和说明中建立,不只是声称“只有程序员读代码”。 详见名称来源取决于概念所属。

number、verb、pluralModifier若孤立出现,需要读完整算法才知它们属于猜测统计消息。GuessStatisticsMessage把这些词与make入口放在同一对象中,再按数量构造单复数字符串,使语境由结构表达。抽类只是一个选择,局部函数也可提供足够上下文;本例字段会随调用更新,复用和重入边界仍需考虑,不能因抽类就声称线程安全。 详见对象语境能组织相关字段。

给每个类加GSD前缀,只会把共同应用背景反复放进自动完成结果,也让本可复用的地址类看似绑定原项目。命名空间已提供的上下文通常无需再复制;确需区分不同协议或版本时则应保留有意义限定。短名胜在足够清楚,不是删掉所有边界信息。 详见项目标签不必污染所有名称。

Address若可能表示邮政、MAC或Web地址,PostalAddress等限定说明的是对象本身的区别,优于附带某应用或账号模块的长标签。给实例命名accountAddress能说明其使用角色,给可复用类型则应描述它代表什么。先分清类型含义与局部用途,才知道哪些词必要。 详见精确限定优于无关的长前缀。

发现更能表达意图的名称时,可以借重构工具一致更新受控代码中的引用,并检查调用和行为仍符合原契约。公共API、外部配置、序列化或反射中的名字可能不在工具识别范围,应先确认再改。后半是把命名建议应用到真实系统的边界提醒;本章未证明所有改名都立即安全、无人反对或无需协调。 详见重命名应验证引用边界。

原书依据 · 38 处

第3章 函数

函数把名称承诺的任务落实成输入、状态变化、返回值及失败路径。本章先用测试页面代码展示层次混合的问题,再讨论怎样拆分、分派与组织参数,随后检查隐含副作用、查询和动作歧义、错误处理及重复,最后给出完整的渲染上下文类。目的不是取得最少行数或零参数,而是让使用者看出每步承担什么责任,并保留可核验的行为。

集中责任有助于表达意图在这里补充为“同一名字下、相近抽象层的步骤可共同完成一件事”。同一概念宜保持词汇一致帮助读者由includeSetup预期includeTeardown;多个参数需要角色与顺序线索也可用关键字式名称提示expected与actual。章节末尾的类名词、函数动词比喻回连类名应显露对象承担的角色与方法名称应对应实际业务责任,不另外生一组重复命名卡。

FitNesse在本章作为基于Web的测试框架出现:示例从Wiki页面取得内容,为测试页加入设置/拆解页,再渲染HTML。理解框架角色能帮助读者辨认PageData、WikiPage等对象,而不是把所有陌生类型当作无关噪声。代码清单标明20070619版本,仅解释该书场景;它没有展示框架全部执行机制或当前接口,本次也未启动服务。 详见FitNesse用页面组织测试。

将长流程拆成有意义的调用,可以把“加入设置、放入正文、加入拆解、渲染”显露出来;原调用的细节转到下层函数后,上层读起来更容易。可读性改善不独立证明变换等价,还应核对异常、输入修改和生成文本等行为。书中几份版本的输出组织与调用时机须按真实场景验证,不能以九行代替正确性证据。 详见抽取调用仍需核对行为边界。

小函数可让目的与调用关系集中在读者视野内,但两三行、二十行等长度只是本章作者经验,不是有研究证明的最佳阈值。判断是否继续拆分,要看新名称是否表达了一个有意义步骤、是否减少混合层次,而非把代码机械压成更多跳转。块内单个调用和浅缩进是该风格的组织手段,也需与完整逻辑和可读性权衡。 详见函数行数阈值只是经验。

一个函数可以有多个步骤,只要它们共同解释名字承诺的一件事,并处于相近抽象层。例如渲染测试页可先处理设置/拆解再取得HTML;具体怎样拼接换行或解析路径放到下一层。高层意图与低层字符操作混在一起,会让读者不断切换问题。抽象层不是按语句类型固定划分,而应看它对当前任务表达的细节程度。 详见同层步骤应隐藏下一层实现。

先给出当前任务,再依次解释它调用的下一层步骤,读者就能由整体走到细节,而不必先读完字符串拼装才知道用途。TO段落法用“为了完成某事,先做哪些事”检查这种结构。它是源代码组织与阅读路径,不是程序执行必然按文件顺序;共享函数或递归也不应为排版强行复制。 详见向下阅读使调用层次可追踪。

单一职责把模块的边界与它为何需要改变联系起来,目的是避免互不相关的变化总碰同一处代码。工资例把不同类型规则集中到相同分派函数,提示类型增加会牵动它。分支多或代码长本身不足以证明存在多种责任;需说清哪些业务规则由不同原因变化,再决定分离方式。 详见单一职责关注变化理由。

当调用者只依赖Employee的工资等接口,新员工类型可通过新的实现参与,而不在每个调用点增加类型判断。这是对选定变化方向保留扩展位置。创建工厂仍可能要修改,增加行为种类也可能影响接口,因此“对修改关闭”不是系统任何文件永远不变,而是降低反复修改稳定调用方的需要。 详见开闭原则围绕选定变化扩展。

EmployeeFactory把记录到具体员工对象的选择集中在创建处,业务调用再经Employee接口取得结果。这样calculatePay、isPayday和deliverPay不必各复制一套类型分派。工厂仍需认识它支持的类型并处理未知值;这只是一种适合该变化方向的结构,不能把所有switch都视为错误。原清单含拼写和括号不一致,不作可直接编译承诺。 详见工厂可集中对象类型分派。

反复尝试描述函数的名字,可以检验自己是否知道它负责什么。若名称总要串联许多不相干动作,应回看是否混合了层次或责任;集中目的后,名字常更容易贴合。命名困难只是调查线索,领域概念陌生或词汇不统一也会造成困难,不能凭名字长就判定函数应拆。 详见命名困难可提示职责混合。

参数增加可能让角色、顺序和组合更难理解,但零参数函数仍可读取字段、全局状态或外部资源。把参数移成实例字段只改变依赖的表示位置,不会自动消灭测试状态或共享责任。先定义函数需要哪些独立信息及其所有权,再选择传参、对象或构造上下文;不要为凑零参数而隐藏必要输入。 详见参数数量不能独立衡量复杂度。

fileExists(path)对路径询问存在事实,fileOpen(path)则把路径用于取得流对象,二者虽各一个参数,责任与返回结果不同。名称应让调用者知道是在提问、取得资源还是变换数据;转换结果宜在返回值上清楚表达。一个参数不是足够的设计标准,资源所有权和失败条件也需要说明。 详见一元调用要区分查询与转换。

passwordAttemptFailedNtimes(attempts)把一次失败次数通知系统,目的不是回答一个静态事实,而是驱动状态或后续处理。这样的无返回入口应在名称和上下文中显露其动作,避免被当作可任意重复的查询。是否允许重试、重复通知或忽略失败属于具体契约,本章只是用事件形式区分输入用途。 详见事件入口应显露状态改变。

render(true)迫使调用者查定义才知道true选了套件模式。若开关实际切换两种完整任务,可用具名入口让差异在调用处可见;若布尔值本就是要查询或保存的领域事实,则不能仅因类型是boolean就禁止。书中也为限制重构范围暂时保留标识,说明接口兼容与局部改进需要取舍。 详见布尔开关可能混合两套动作。

Point(x,y)有约定的坐标含义,assertEquals(expected,actual)的先后则需要调用者记住接口约定。可用清楚参数名、合适对象和具名调用等方式减少混淆;把参数放进对象还应有真实概念,不能只为少一个逗号。参数数目提示负担,决定好坏的仍是这些输入如何共同表达任务。 详见多个参数需要角色与顺序线索。

assertEquals(1.0,amount,0.001)多出一项参数,却说明允许的数值偏差。JUnit4.13.2的delta表示最大差值阈值,不应把这一固定0.001称作按数值比例缩放的相对误差。容限要对应计算与业务目的,不能为了少参数省掉必要条件;该调用是接口说明,不是本机已通过的断言。 详见浮点容限要对应比较目标。

makeCircle(x,y,radius)中的x和y共同表示圆心,合为Point center后,调用者能按圆心与半径两个概念理解输入。对象化的价值是命名、约束和共同演进的边界,不只是把多个值打包。独立参数若无共同责任,强行放进一个无含义容器反而可能隐藏需求。 详见参数对象应表示共同概念。

可变参数把多项实参收进一个数组式输入,调用点数量可变,任务含义却仍需解释。String.format的格式串决定每个位置怎样被使用,name和hours不因都在Object数组中就可随便互换。按概念统计参数可帮助设计,但不能把打包后的一个形式参数当作没有内部结构或组合负担。 详见变长参数仍要说明元素角色。

checkPassword看似只验证凭据,成功分支却调用Session.initialize,可能清除已有会话状态。调用者必须额外知道“何时初始化安全”,查询外观于是隐藏了调用时机限制。应让真实动作及边界可见;只换成长名字虽能提醒,仍未分离验证与初始化责任。本例是说明性代码,不作完整认证设计或安全部署方案。 详见隐含副作用会产生时序依赖。

appendFooter(s)难以分辨是把s追加出去,还是向s中追加尾注。report.appendFooter()让被修改对象成为接收者,返回新结果的转换接口则可表达另一种所有权。输出参数并非语言上不合法,关键是调用者能否看出谁被改变、结果在哪里;把状态移到this也不自动消除副作用或线程共享。 详见接口应让数据修改方向可见。

attributeExists负责查询存在性,setAttribute负责设置;if(set(…))若让人分不清问旧状态还是执行了赋值,就需要明确责任。分开查询与动作可改善表达,但并发下先查再改不保证条件仍成立。需要一次完成的设置动作可以返回“已设置”等业务结果,未执行与失败分别表达;不能仅为调用方分支控制而返回“该不该继续”。 详见查询与动作应有清楚的结果语义。

连续操作若每步都返回错误码,调用处可能积累嵌套分支;异常可让失败离开当前主路径,在相应边界统一处理。两种方式都须让调用者知道失败含义,不能因为日志集中就假定问题已恢复。删页面、注册表引用和配置键是多步效果,后步抛异常不会自动撤销前步,书中没有提供事务或补偿保证。 详见异常可分开失败路径与主流程。

delete可组织错误策略,deletePageAndAllReferences执行主要操作,logError记录失败,分工后读者能分别查看每种责任。是否捕获并吞掉、转换还是继续传播,仍应由业务契约决定。try必须是首词、之后不能有代码是本章风格偏好,不是语言或所有资源清理设计的约束。 详见错误处理边界也需要明确责任。

很多调用方共用一份错误枚举时,新增含义需要考虑它们怎样解释、记录和处理,旧码复用可能让失败原因失真。但新增或重排Java枚举常量并非必然破坏旧二进制,规范仍提示旧穷尽switch遇到新值可能失败。异常层次也不自动免除新语义处理和发布验证;应区分依赖治理、源码修改与二进制兼容。 详见共享错误表会扩大语义依赖。

设置和拆解四段都要找继承页、取完整路径、拼接include指令,差别在页面名与setup/teardown参数。提取共同步骤时把这些变化点作为明确输入,可减少同一算法改四处的风险。应先确认四段真遵守同一规则;文字相似不等于全部行为可合并,也不应以消重为由混淆顺序和失败条件。 详见共享步骤应显式表达差异。

单入口单出口约束能限制一些复杂控制流,但小而清楚的函数有时用提前return、break或continue更容易表达。判断重点是读者能否追踪退出条件,以及资源清理、结果和副作用是否保持契约。这里解释本章对严格单出口的取舍,不把它当结构化编程的唯一完整定义,也不因函数短就免查遗漏清理。 详见提前返回也可保持局部清晰。

初稿可先把所需行为和对应测试建立起来,再逐步拆分、改名、消重和调整位置,每一步检查已知行为仍满足约束。这让整洁成为反复加工的结果,而不是一次写出完美函数的资格要求。测试只覆盖实际断言,重构还需检查输入状态和边界;“覆盖每行”不是行为完备证明。 详见先建立行为再迭代函数结构。

SetupTeardownIncluder的静态render每次创建一个处理对象,把页面、crawler、套件标记和缓冲放在该次调用上下文中,再由小方法按设置→正文→拆解→更新的顺序协作。少参数来自状态被收拢,不是状态消失。对象最终仍修改传入PageData;新建包装对象不保证输入不可变、重复调用幂等或与初版生成文本严格等价。 详见调用级对象可收拢渲染上下文。

原书依据 · 70 处

第4章 注释

函数和名称已经能表达的内容,不必再逐句翻译成另一份文本;但背景理由、外部契约和不直观约束也不会自动从代码显现。本章围绕这两种情况区分注释用途,接着用漂移、复述、远处默认值、残留代码和格式负担说明维护风险,最后以筛法对照展示如何同时改善代码与保留必要解释。判断标准是信息是否准确且帮助理解,而不是注释越少越好。

将位标记判断命名为employee.isEligibleForFullBenefits,延续了行为接口可隐藏状态表示;把异常处理抽成函数却仍留空catch,也提醒抽取调用仍需核对行为边界。因此这里的“好读”没有被用作完成等待、错误恢复、排序契约或并发安全已经成立的证据。

注释与代码各自保存一份信息,移动、修改或复制其中一份后,另一份可能失去对应。HTTP日期例的解释被其他字段隔开,就增加了定位与维护成本。读者应核对实现和适用条件,而不是因为有注释就相信它;这也不意味着所有注释都是失败,代码未显露的理由与约束仍值得说明。 详见注释需要随所指代码共同维护。

项目可能在文件头保留版权或发布条件等固定信息,它承担来源和项目约定的说明用途,不是重复函数做什么。书中FitNesse用短声明指向统一许可文本,避免把大段条款混进实现说明。这只是该项目的展示方式,不能从中推出任何文件的通用法律义务;具体保留内容应以所属项目实际要求为准。 详见固定发布声明不等于功能注解。

注释能交代“为何这么做”,例如为何把本类型排在其他类型之后,或为何启动大量线程尝试撞出竞争。但知道作者目的,还需要检查比较契约、测试等待和失败条件是否成立。说明不是把错误设计变正确的凭据;保留理由能帮助后来者评价与替换它,而不是阻止质疑。 详见说明意图不等于证明方案正确。

并发测试启动许多线程后立刻读取AtomicBoolean,可能只看到当前尚无失败,工作却还没结束。原例未展示join或其他完成协调,因此不能由assertFalse式结果证明全部线程处理成功。需先定义参与者和完成条件,再汇总已发生结果;原子可见的标记不负责等待其他工作完成,本次没有启动这些线程。 详见失败标记不能代替完成等待。

当库函数或受限接口不便改名时,局部注释可以解释参数顺序、返回值符号或特殊条件,减少读者来回查找。解释应准确指向当前调用并与对应版本相符;若能通过合适包装或名称清楚表达,也可减少重复说明。注释翻译仍可能出错,不能因为它看起来容易读就免查契约。 详见外部接口的约定可就地阐明。

compareTo的一般约定是负数、零、正数分别表示小于、相等、大于,不保证所有实现只返-1或1。测试若只想验证排序,应避免把符号要求误写成固定返回值;实现若另有明确契约才可更强断言。顺序还需反向符号与传递性一致,注释写“我们更大”并没有自动满足它。 详见比较结果应先按符号解释。

耗时极长的测试或有共享状态限制的工具,值得在相应入口说明代价、触发条件及为何采取特殊处理。测试被禁用时也应给可追溯原因,而不是让人误以为已经通过。注释只能提醒,是否执行、怎样隔离与检查仍由实际流程负责;方法下划线与@Ignore是书中不同年代的测试约定。 详见警示应保留危险条件与理由。

SimpleDateFormat实例包含可变处理状态,多个线程并发共用时需要外部同步,或各自使用独立实例。书中方法每次新建并提示原因,防止后来者为省分配改成无保护共享对象。独立创建后若又交给多线程共享,限制仍会回来;这一片段也没有完整证明所有HTTP日期格式、地区设置与调用需求都已满足。 详见共享格式器须明确同步边界。

TODO说明尚未实现、将删除或等待条件变化的工作,让读者知道当前状态与期望之间的差距。它应有足够上下文并定期重新判断是否仍必要,不能替代应完成的实现或成为长期保留坏行为的理由。工具能找到TODO,只说明容易检索,不证明有人负责处理或承诺已经兑现。 详见TODO记录待办而非完成证据。

trim在列表项处理中不只是美化文本:前导空格可能让后续解析把它识别为另一层列表。记录这种不直观后果,能帮助维护者避免随手删掉必要步骤。说明应对应真实语法和输入范围;这个例子不证明任意空白都应删除,也不将字符串清理当通用数据规范化。 详见注释可解释看似多余的操作。

公共API的使用者通常不该先读完整实现才能调用它。说明应帮助理解有意义的输入、结果、失败及约束,提供名称之外真正需要的信息;代码与文档变动时也要同步。短方法不天然免除契约说明,私有方法也可能有复杂不变量;是否写Javadoc应以读者需要为依据,而非要求每个符号填同样模板。 详见公共文档应补足调用者契约。

loadProperties捕获IOException后留空,再写“没有文件就已加载默认值”,没有告诉读者默认值在哪里建立,也没有证明异常只代表文件缺失。若恢复是所需契约,应在实现或相应边界说明其真实来源及失败处理。注释不能代替未发生的加载,更不能让所有I/O错误自动成为可忽略的正常情况。 详见注释不能凭空补出恢复行为。

“返回月份的日数”若只把getDayOfMonth重新说一遍,没有解释范围、单位或不变量,就增加了一份会漂移的文本。自动要求每个字段或构造器有同款说明,容易产生这种噪声,复制时还可能把version贴到info上。应检查注释是否补充读者需要而代码未表达的信息,不能仅按注释数量判断文档充分。 详见注释须提供名称之外的信息。

waitForClose只在特定检查点看closed。另一个线程改变条件,并不自动使等待线程立即返回;还涉及通知、重新取得锁、超时、中断及伪唤醒。书中单次wait后再检查的样板也不能保证严格等到期限;完整协议通常需循环检查条件并核算剩余等待。timeout为0还表示不按该时长自动超时,注释不能掩盖这些边界。 详见条件变化不会自动唤醒等待者。

把每次修改和署名堆在文件头,会让当前实现被过往清单淹没,负责人变化后标签也可能失真。已有可追溯版本记录时,可将时间、作者和变更说明放到适合的记录系统,源码注释集中解释当前技术决策。项目要求保留的来源声明是另一用途;历史能否恢复取决于真实提交及保留范围,不是工具名称的保证。 详见变更历史宜保存在版本记录中。

长分隔线、Actions栏和右括号后的while标记,可能帮助偶尔定位,也可能淹没真正内容。若反复需要标记才能知道自己处在哪个嵌套,宜先检查函数层次和职责。少量有明确导航价值的标记可保留,不必为了反对装饰把生成代码或特殊布局一律重写;目标是降低定位负担。 详见定位标记不能替代清楚结构。

旧实现长期以注释保留,读者难判断它仍有计划用途还是早已废弃,容易形成不敢清理的残留。若该版本已被可靠记录,可在当前源码移除无效分支,让历史承担恢复用途。尚未提交、被排除或丢失的历史并不会由版本工具自动保存,因此清理前要辨认范围;这与保留解释“为何不用某方案”的短说明不同。 详见注释代码不应充当长期备份。

注释既可能在编辑器里阅读,也可能被工具生成网页。大量转义和布局标签会妨碍源码阅读,但适当的代码块、链接和列表也可能对生成文档必要。应选能同时表达语义并便于维护的格式,再检查生成结果,不把“工具负责呈现”理解成所有Javadoc HTML都不合法或都应删除。 详见文档格式要兼顾源码与生成物。

setFitnessePort只保存传入值,却在注释承诺默认8082,默认值真正变化时这里未必有人同步。实现并不掌握的系统事实,应在其真实来源维护,再通过稳定引用或统一配置让读者找到。就地说明仍可提相关约束,但要明确它依赖哪里,避免多处独立抄写同一默认值。 详见说明应靠近事实的维护来源。

对完整的24位输入组,Base64把三个8位字节重排为四个6位索引,再用相应字母表符号表示。因此这里四个输出符号仍表达原来的24位信息,并没有增加保密性。原书借RFC2045片段讨论注释是否太长;其中机制仍可独立理解,但尾组和填充等规则未在该段完整展开,不能把它当完整编解码器规范。 详见Base64把三字节映成四符号。

缓冲长度公式里的+1、×3和+200若各有设计原因,应让读者知道每项分别代表什么以及适用条件。笼统说“像素、过滤字节和头部”仍不能准确对应公式,反而使人继续猜。可用有意义的命名或精确说明解释,不能仅因为数字被一段长注释包住就认为容量计算已正确。 详见注释应把常量与原因对应起来。

先考虑2到上界的整数,依次找到未被排除的数并标记它的倍数,剩下的就是素数。若一个数是合数,它至少有一个不大于自身平方根的因子,所以不必对每个大数都重新排倍数。书中用数组索引表示整数并从2的倍数开始;平方根取数组长度是略保守边界,性能收益仍要按负载判断,未在本机运行。 详见筛法按小因子排除合数。

new int[0]返回长度为零的有效数组,可以按空结果处理;null则没有数组对象,调用者访问长度或遍历前有不同责任。生成素数上界小于2时,原代码实际给空数组,旁注“null array”容易误导。应让接口与说明分别明确无结果、无对象和失败含义,不能用近似措辞替代实际返回语义。 详见空数组与空引用不是一回事。

重构后的PrimeGenerator把crossedOut和result放进静态字段,小方法共同操作它们。这样拆分了步骤,却让多次并发调用共用工作区;private只限制访问位置,不让每次调用自动独占。若在共享服务中使用,需要另定状态所有权与同步方案,不能仅因命名清楚、注释变少就断言线程安全。原书未提供这部分并发保证。 详见抽取函数不消除静态共享状态。

原书依据 · 42 处

第5章 格式

前面用名称、函数和注释组织意图,本章再用空间布局帮助读者找到这些意图。空行区分概念,接近表示联系,缩进显示范围,行宽与水平空格减少来回查找;团队规则则让这些线索跨文件保持一致。尺寸图和CodeAnalyzer用于说明观察方法及风格选择,不是给所有代码判质量的通用计量表。

报纸类比、调用者在前以及相关函数相邻,延续向下阅读使调用层次可追踪;字段间反复插入无信息的注释,回连注释须提供名称之外的信息。这些是同一思想在布局中的运用,故保留补充位置而不重复生成卡。布局清楚仍不替代资源关闭、统计样本和真实行为的检查。

七个项目的文件分布说明,有些完整系统可以由较短文件组成,却不证明某个行数是所有项目的最佳值。两百或五百行应作为检查组织方式的线索,不能替代对职责和阅读路径的判断。图中方块的σ范围在正文与脚注描述不一,作者也承认只为取得感觉,故不据此宣称精确覆盖比例或长度与质量的因果。 详见文件长度样本只是设计线索。

文件长度图的纵轴依次标1、10、100、1000等量级,相近的轴距离代表相近倍数变化,而不是相同新增行数。读图时需先识别尺度,不能把100到1000与1到10当成相同绝对增量。书中借此容纳差别很大的文件,图示仍只是所选项目的样本分布,不是当前仓库测量。 详见对数轴上的距离表示倍数。

包声明、导入、字段组和函数之间的适当空行,让读者在扫视时辨认新的概念段落。把所有行挤在一起,即使执行内容类似,也会增加分组成本。空行应对应信息结构,不能机械地每行一空或用大量空白假装职责已经分开;效果还要结合团队格式和实际展示判断。 详见空行可标记概念边界。

共同完成一项任务的声明与操作靠近,读者较容易在同一处取得必要上下文。无信息增量的注释或随意分散的位置会切断这种关系。接近是降低查找成本的组织手段,不意味着所有调用相关类都应塞进一个文件;跨模块边界、复用与职责分离仍可能比物理距离更重要。 详见相关代码宜减少查找距离。

短方法中在使用前声明局部变量,循环变量放在循环入口,可让读者同时看到其含义、初值和有效范围,减少回头寻找。需要跨try或其他块使用的资源,要按实际生命周期安排;把声明移近并不保证它已正确关闭。书中readPreferences只在异常分支关流,不能作为完整资源管理样板。 详见局部声明应贴近使用范围。

实例字段通常服务于多个方法,把它们放在团队约定且易找到的位置,能减少读者偶然撞见声明的情况。Java类顶部是本章采用的惯例,其他语言或团队可能不同;核心是位置可预期。字段列表和使用分布还可提示内聚性问题,但仅凭字段多或位置不顺就不能断言类必须拆分。 详见成员位置应形成可预期约定。

调用getPageNameOrDefault时由上层传FrontPage,能让默认首页策略在读者看得到的业务入口出现,通用取名函数只负责按传入规则处理。若把常量藏进底层,策略改变时可能难找且限制复用。不是所有常量都应提升为全局,而是让选择与它所属的责任层一致。 详见默认策略留在作决定的层级。

assertTrue/False及带消息/不带消息的变体属于同组使用概念,即使彼此没有直接调用,也可放在一起便于比较和选择。布局相关性不只来自调用边,还来自共同任务、词汇和接口角色。相同名字外形仍需对应真实语义,不能按字母或模板把不相关操作强行分组。 详见相似操作也有布局上的内聚。

过长代码行要求读者横向移动才能看到同一表达式,会打断上下文。可在语义边界换行,并结合常用屏幕、评审视图和团队规则确定宽度。八十、一百或一百二十字符是本章讨论的经验范围,七项目分布没有证明人类阅读的唯一上限;缩小字体塞更多内容也不必然更易读。 详见行宽应服务于完整阅读。

赋值两侧空格可突出左右角色,逗号后的空格帮助分辨参数,调用名与括号靠近则提示整体。作者还用乘法紧、加减较松来暗示优先级,但空格不会改变语言的运算规则,括号和真实语义仍要清楚。格式器可能按团队统一策略处理,细微排版不应成为唯一解释依据。 详见水平空格可提示表达式分组。

手工把所有变量名或右值排成一列,可能突出列而遮住类型和赋值关系,也会增加随名称变化调整空格的工作。若列表很长,先问其职责是否清楚,而不是只靠对齐改善外观。表格式数据在某些场景仍有阅读价值;本章表达个人偏好,不足以证明所有列对齐都错或十个字段必需拆类。 详见水平对齐不能替代职责审视。

类、方法、条件块及内部语句通过缩进显示包含关系,读者可沿左边界辨认自己正处在哪个范围。这里的层级是代码词法嵌套,不是对象类型之间的继承关系。缩进应与实际括号和语言语法一致,不能用看似漂亮的空格掩盖错误归属;小函数也需保留足够清楚的边界。 详见缩进表达词法嵌套范围。

while条件中已执行读操作时,循环体可以为空;结尾分号若藏在同行末端,容易被误看成普通代码块入口。应让空体位置和意图明显,或选更清楚的结构。空体不代表没有工作,条件本身可能有I/O副作用;也不能仅凭视觉显式就证明停止、资源关闭或错误处理已完整。 详见空循环体应显露控制边界。

成员共同选择简单格式并落实到IDE或格式器,可让不同文件使用稳定视觉约定,减少每次阅读和评审都重新适应。个人偏好未必全被采用,团队一致是协作成本的选择,不是规则天然最优。自动化只负责可表达的格式部分,命名语义、职责和行为仍需人判断,不能由格式检查成功宣称代码整洁已验收。 详见团队格式规则应进入工具配置。

CodeAnalyzer逐行取line.length并累计行数和直方图,平均值由totalChars/lineCount得到。它测的是读取后字符串长度,不等同屏幕列宽或含换行的文件字节数;制表符显示宽度也未由一个字符数表达。字段在analyzeFile间不重置,可形成累计样本,应说明统计边界;空输入和资源关闭仍需另定,本例没有完整处理。 详见长度统计先明确样本与单位。

按已排序宽度累计频次,首次超过lineCount/2就返回,会在偶数样本中选上面的中间值。教学演算:两行宽度为3和5,这段规则返回5;常见数值中位数取两者均值则为4。应说明使用上中位数还是平均中位数,而非仅靠方法名让读者猜。这里是按代码推导,不是本机统计结果。 详见偶数样本中位数需明确约定。

原书依据 · 33 处

第6章 对象和数据结构

本章从访问修饰符继续追问:调用方究竟需要知道多少内部结构?Point和Vehicle说明封装要表达稳定能力;两套形状实现说明类型与操作是不同的变化轴;ctxt创建流的例子则把遍历结构改成委托目标操作。最后区分传输、持久化与业务规则的角色,使选择面向对象或过程式组织都有具体理由。

这延续前面函数职责与抽象层级的主线:让对象完成目标操作解释为什么仅拆短调用链还不够,扩展方向决定数据组织则为变化边界提供判断条件。持久化与规则边界需要选择明确标注本书与Fowler对Active Record的取向差异,避免把一种设计偏好读成模式定义。

把字段改为private并逐一生成getter/setter,仍可能让使用者依赖相同的数据形状。真正需要保护的是可变化的表示选择。Point同时提供笛卡儿和极坐标操作,使用者不必知道内部存哪套坐标;接口是否构成良好抽象,要看它承诺什么业务能力,而不是是否出现private或interface。 详见封装需要隐藏表示选择。

Point可单独读某个坐标,却用setCartesian(x,y)或setPolar(r,theta)一次提交一组坐标。这使接口表达完整位置更新,而不是要求调用者猜测先后设置的中间状态。原文称其原子操作,但只给接口声明,未给锁、内存可见性或实现;不能据此宣称多线程读取必然看见一致快照。 详见成组设置表达一致性边界。

读取剩余燃料比例,使只关心余量程度的调用方不必知道容量单位和存量表示。分别暴露加仑容量与存量则把换算责任交给调用者。选择取决于真实需求:需要绝对续航量的操作仍可能需要其他能力。比例接口还需说明范围及单位约定,不能因方法名含Percent就假定返回0到1或0到100。 详见按使用问题选择数据抽象。

形状若是数据记录,集中在Geometry实现面积,可添加周长操作而不改记录;新增形状则需检查各操作的分支。形状若各自实现多态area,新增类型可增加实现;新增必需操作则可能涉及所有类型。应先看哪条变化轴最常发生,再选组织方式。Visitor、双向分派等可改变取舍,原书脚注也承认额外成本,不把二分描述当所有语言唯一方案。 详见扩展方向决定数据组织。

Geometry.area逐个识别Square、Rectangle、Circle,未匹配就抛NoSuchShapeException。新增形状时,遗漏某个集中操作的分支会走未知类型路径;多态方案把已有操作的实现义务放到新类型。示例用于对比扩展位置,未列构造与尺寸校验,不能因此宣称其已处理负半径、所有输入或完整形状API。 详见按类型分派要处理未知输入。

本章用当前对象、参数、当前创建对象和直接持有对象描述方法的近邻,意在避免跨层了解对象内部。原则关注必要耦合,不是数句点:东北大学的对象形式还讨论计算出的直接部分、集合成员等细化。应结合对象关系和实际责任判断,不把本章“任何返回对象都不可调用”的简写当全部形式的严格定义。 详见得墨忒耳律限制结构知识。

把ctxt.getOptions().getScratchDir().getAbsolutePath拆成三个局部变量,只改变表达和调试入口。调用方仍知道上下文有选项、选项有临时目录、目录能给路径;这些结构一变仍会影响它。判断封装是否改善,要看所需知识有没有减少,不能因每行只剩一个方法调用就认定已解耦。 详见拆开调用链不减少结构依赖。

公开的数据结构本就让使用者读取组成部分,连续字段访问不自动说明破坏了它承诺的行为封装;有行为的对象若要求调用方穿透内部,则值得重新划分责任。getter存在不能单独区分两者,因为框架也会为纯数据要求存取方法。即便数据遍历合理,仍需承担结构版本、空值和输入可信度等契约成本。 详见数据遍历与对象协作需区分。

取得临时目录路径后再拼类名、扩展名并创建流,暴露了调用者原本只想获得输出流这一目的。把能力表达为ctxt.createScratchFileStream(classFileName),可让路径策略留在上下文内部。该签名只是责任方向,不自动保证名称校验、路径安全、失败处理或流的关闭;这些契约仍须在实现和调用处明确。 详见让对象完成目标操作。

一边提供执行业务规则的方法,一边让外部随意改同一内部数据,可能让约束被绕开,也使类型和操作两种变化都难隔离。应明确哪些是传输数据、哪些对象负责规则,设计受控更新边界。不是所有带getter的对象都必然混杂;只读投影或明确契约应按实际是否泄露表示、破坏规则判断。 详见公开可变数据会绕过对象责任。

DTO为数据库交接或消息解析携带数据,之后可经转换进入有业务规则的模型。它的价值在明确数据形状与边界,不要求一定有业务方法。Address示例用私有字段、构造器和getter,外观像对象仍主要承担传输角色;本例没有setter和校验,不能将其说成可任意修改或已保证所有地址合法。 详见传输数据不等于领域对象。

本书建议把Active Record当数据载体,将业务规则放入另一个隐藏内部数据的对象,以保持其主张的对象/数据结构边界。Fowler模式目录则明确定义Active Record可以封装行访问并加入该数据上的领域逻辑。因此,分离是本书的设计建议,不是该模式禁止业务规则的定义;应按规则复杂度、持久化耦合和项目契约决定边界。 详见持久化与规则边界需要选择。

原书依据 · 14 处

第7章 错误处理

第6章讨论对象应该承担什么操作,本章接着讨论这些操作失败时向外表达什么。先区分主流程与错误边界,再从文件失败测试、受检异常、上下文消息和厂商包装建立失败契约;餐食补贴与空列表则说明,有些看似异常的情况实际是正常业务变体。最后以参数null和断言提醒:可读的失败处理仍要在真实运行配置中有效。

异常可分开失败路径与主流程与错误处理边界也需要明确责任延续第3章,这里补充关闭设备和边界处理的原文位置。异常控制流不自动回滚状态明确区分控制转移与事务保证,特例对象可承接正常业务分支则将第6章隐藏行为的思路用于正常变体。异常分类、默认结果和参数校验都应以业务契约为依据,不能只为让调用者少写一条分支而掩盖失败。

DeviceController把关闭步骤移到tryToShutDown,把日志放在外层catch,使两种责任易分别阅读。但新版片段不再显式判断DEVICE_SUSPENDED,依赖的其他实现又省略了,不能只因更短就认定与旧版行为相同。重构时须列出有效/无效句柄、暂停状态以及每步失败后的预期,核对被抽走的条件由谁承担。 详见异常重构仍需核对业务分支。

开始读文件逻辑前,先明确不存在文件要怎样反馈,再用能触发这一条件的测试约束实现,可让失败行为成为接口的一部分。占位实现、宽泛捕获到缩小异常范围,是书中展示的迭进步骤;一次异常测试不会证明读取成功、内容解析和资源释放全正确。书中“测试通过”是叙事,本轮未执行。 详见先定义失败后的可观察契约。

try/catch规定失败后转移到哪里,不能撤销已经完成的文件写入、设备动作或业务变更。原文把try比作事务,是帮助先设计失败边界的类比;一致性仍需明确恢复、补偿、资源释放或真正事务机制。即使catch记录并返回,也不能由捕获成功推断业务已恢复到原状。 详见异常控制流不自动回滚状态。

retrieveSection最终片段只catch FileNotFoundException,但FileInputStream.close仍声明IOException;若方法未另行声明或处理,所示签名不构成完整可编译实现。未来在打开与关闭之间加入读取,失败也可能绕过普通close语句。缩小catch须逐步检查实际可能抛出的异常,并设计覆盖失败路径的资源清理,不能机械替换异常名。 详见缩小捕获前要清点全部异常。

Java受检异常在未被本层捕获、又未被已有合适throws声明涵盖时,会要求沿调用路径补充处理或声明。这样能让失败显式进入契约,也可能让底层细节影响高层。本书一般偏好非受检异常,但这是成本取舍;非受检不表示错误无法处理,也不能据此省略失败契约。并非每次增加子类型都必然修改所有层或破坏二进制兼容。 详见受检异常会传播接口义务。

堆栈展示执行位置和调用路线,却未必能说明调用者在做哪项工作。异常应携带失败操作、必要对象上下文和原因,使边界处理器能辨认失败来源。包装底层异常时保留cause有助于追索;记录上下文仍应按项目约定选必要字段,不能把日志存在当恢复成功,也不需要在每一层重复记录。 详见错误信息要交代失败意图。

若调用方对几个厂商设备异常都采取相同报告动作,可由LocalPort统一翻译为PortDeviceFailure并保留原始原因,减少重复catch。若某类失败需要不同恢复、重试或继续策略,就应保留可区分的类别或信息。异常分类服务实际处理责任,不是把所有错误压成一个名字;本例的统一适用于已展示的共同处理情形。 详见异常分类应对应处理差异。

应用直接依赖厂商构造和异常名称,会让替换与测试都被其设计牵动。本地包装把应用需要的open能力和错误契约集中起来,应用在这一边界协作,厂商细节留在内部。包装不保证随时零成本换库;底层行为差异和清理责任仍需实现及核验,模拟边界也不能代替真实适配的验证。 详见第三方边界可用本地接口隔离。

餐食报销例规定:有消费计实际额,无消费计每日补贴。“没有消费”本身是正常政策分支,可返回实现MealExpenses的PerDiemMealExpenses,让调用方统一取total。应只在已确认符合补贴条件时选择该对象,数据源失败不能冒充无消费;特例也不是固定零值,具体总额由其业务语义决定。 详见特例对象可承接正常业务分支。

getEmployees若已成功确认没有员工,可返回空列表,使调用方统一遍历,零次迭代自然不累加薪资。应把“确实没有”与查询失败、尚未加载等状态区分,否则默认空集合会掩盖缺数据。Collections.emptyList不可变,调用方若需要添加成员必须有明确可变集合契约;空列表也不能防止其他引用或元素为null。 详见空集合适合表达确定的零结果。

registerItem即使检查item和registry,仍解引用persistentStore、existing及billingPeriod,任何没有约定的缺失都可能导致失败。继续添加if不一定说明缺失应该跳过、报错还是视作正常空值。应先明确每个边界允许哪些状态及对应结果,再用校验、异常或特例表达;普通非错误跳过不能伪装成动作已成功。 详见层层判空不能代替数据契约。

xProjection要求两个点存在,否则无法按给出的公式读取坐标。接口应说明null是否有业务意义,并在适当入口拒绝非法输入,让调用者得到清楚的责任反馈。原文异常版本缺new且未提供异常定义,公式也只有教学比例1.5,不能当完整投影库;声明“不传null”仍需与实际实现和调用遵守相配合。 详见非空参数约定需要可执行边界。

Java assert可表达开发时不变量,但未启用时条件不会作为强制校验执行。xProjection只用assert检查p1/p2,不能保证所有运行配置都以断言消息拒绝null;后续访问仍可能抛NullPointerException。面对外部输入或公开契约,应采用运行配置下明确生效的检查,断言通过也不证明全部业务条件成立。 详见断言不应承担公开输入校验。

原书依据 · 18 处

第8章 边界

外部接口通常比应用实际需要更通用,也不由应用独自决定其演进。本章以Map说明只暴露所需能力,以学习性测试把API理解变成可重复的试验,再以尚未完成的发送器API说明:本地先定义需求,之后由适配器跨接,而非让业务代码到处依赖厂商细节。

第三方边界可用本地接口隔离在第7章侧重异常翻译,本章将同一责任方向延伸到容器能力、API学习和未知组件。泛型约束与操作权限不同提醒类型正确仍可能能力过宽;假实现与真实适配分层验证则用原书类图区分控制器的测试接缝与未来真实API的验证。学习测试只有明确预期、受控环境并覆盖实际依赖,才能为后续升级提供对应范围的证据。

Map能查找也能修改、清除,提供者追求通用性,业务使用者可能只需要按ID取Sensor。直接把可变容器交出去,会把原本不想授予的操作一并暴露。Sensors.getById可缩窄可见能力,但返回的Sensor本身是否可变仍需契约。Map的修改方法是可选操作,具体实现可能拒绝clear,不能把“有这个方法”说成任何Map都能成功清空。 详见通用容器不等于业务能力。

有类型的键值声明能让正常使用的Java泛型API在编译期约束键和值,减少调用端强制转换;它不会因此删除clear等业务不愿开放的方法。原文Map和HashMap少了键类型参数,不能照抄为有效Java泛型。按本例String ID,应分别表达键和值类型;原始类型或不安全混用仍可能绕开约束。 详见泛型约束与操作权限不同。

Sensors把取出、转换和容器选择留在内部,让应用其他位置依赖业务查询能力,未来更换内部表示时少碰调用方。封装价值来自变化或规则集中,不是每用一次Map就要造一个包装类;书中也明确反对一律封装。采用泛型的历史迁移成本是案例背景,不能推断Java5使所有旧Map调用强制失效。 详见边界封装应集中真实变化点。

先在隔离的小测试中按预期使用第三方API,核对配置和行为,再把稳定的理解整合进应用,可避免同时调试库的用法和业务逻辑。它检验的是自己所需的使用方式,不承担穷尽测试第三方所有功能的责任。隔离应包括共享配置、环境与外部资源,测试存在本身仍不证明预期已被自动检查。 详见学习性测试把理解变成试验。

log4j例依次尝试Logger、Appender、Layout和输出目标,并把得到的配置写进小测试,有助于保存探索路径。但所示方法主要输出info,没有对捕获输出作断言;“看见hello”是书中人工观察,JUnit方法正常结束也不必然代表日志目的实现。它是历史API示例,不能照搬为当前库配置或本轮运行结果。 详见观察性试验需补明确判据。

LogTest的@Before移除命名logger和root logger的所有Appender,能影响相同进程中依赖这些日志器的其他测试。准备阶段清空配置不等于测试结束后恢复原状态;应说明隔离范围、顺序依赖和清理责任。书中用它探索配置,不足以证明该套件可任意并发或与生产配置共享运行。 详见测试配置也可能污染共享状态。

把生产实际调用方式和预期输出写成边界测试,换库版本时可重复检查已有依赖是否仍成立。这能降低迁移的不确定性,不能保证未测行为、部署配置或所有兼容性均无变化。书中“免费”指学习工作可沉淀为测试,不是编写、维护和运行毫无成本;失败需要判断是库变化、环境还是旧预期不当。 详见升级边界测试只覆盖所测契约。

发送器API未确定时,团队从调用方要完成的事定义Transmitter.transmit(frequency,stream),让CommunicationsController先表达发送意图;后续适配器再把本地需求映射到真实API。这样可推进受控部分,但频率单位、流生命周期、错误和时序契约仍要协商,不应把猜测接口当已获得外部实现承诺。 详见未知外部接口可先定义需求。

FakeTransmitter让控制器在本地接口处接受可控替身,验证自己的协作逻辑;真实TransmitterAdapter还需边界测试,确认其正确使用未来API。假实现通过不证明真实发送、电气行为或集成已成功。图中的接缝使替换可能,适配器集中映射可减少变化点,但外部契约的重大变化仍可能影响本地接口和业务。 详见假实现与真实适配分层验证。

原书依据 · 10 处

第9章 单元测试

前面已把依赖边界变成可替换的接缝,本章进一步问:保护这些行为的测试本身怎样才能长期可靠?计时器故事把人工等待改为可控条件;TDD纪律让变化保持小步;测试语言和构造、操作、检验使行为意图可读;单概念与FIRST则约束运行和判定。测试的价值来自有效预期、受控条件和可持续使用,而不是测试文件数量。

可控时钟让时间条件可检验接续第8章的替身边界,自足验证要自动判定预期则补上观察性试验需补明确判据所指出的日志观察缺口。一个测试应聚焦一个概念把第3章的函数职责用于测试组织;日期加月可能不满足分步合成说明拆开场景有助于看见缺失边界与具体契约。所有通过结论仍限于实际检查的输入和预期,不能由高覆盖率推断全部正确。

真实等待五秒并人工观察输出,难以快速重复或精确辨认触发边界。Timer例改为隔离系统时间,让测试推进假时间并检查命令标志,可分别验证未到期、到期等预期。替代时钟只控制测试所建模的时间,不自动模拟线程调度、竞争和真实时钟特性;仍需按责任决定其他验证。 详见可控时钟让时间条件可检验。

一次演示后丢弃驱动,会让后来修改者失去可重复的行为检查。把测试与代码一同版本管理并让使用者方便运行,能保存当前的预期和复现入口。保存的价值还依赖依赖项、运行说明和断言是否有效;文件存在、曾通过或覆盖了某行,都不能证明新环境中的全部行为正确。 详见测试应和实现一起保存。

本章三条纪律要求先有失败测试、只写足以失败的测试,再写刚好让当前失败通过的生产代码,形成小步反馈。编译失败也可成为早期反馈,但最终需要真正执行并检验行为。约三十秒和年产千例是作者描述的节奏,不是普遍指标;遵守步骤也不自动保证测试完备或覆盖所有需求。 详见TDD用失败限制本次增量。

生产行为演进时,难读、耦合过多的测试往往也要修改。若维护反复消耗时间,团队可能减少运行乃至弃用,进而失去反馈并害怕重构。应把测试当长期代码维护其命名、职责和表达。原书团队故事说明这条可能的反馈链,不证明所有失败皆由脏测试造成,也不意味着一个欠佳测试必然比没有测试更坏。 详见测试维护成本会反过来阻碍改动。

页面测试把路径解析、响应器创建和请求构造混在期望之间,读者要先还原技术细节才能知道测什么。makePages、submitRequest和assertResponseContains等辅助函数把这些细节收拢,让场景和期望在测试表面可见。封装仍须语义准确且可追索,不能让不透明helper掩盖关键输入、断言或副作用;本章未列所有helper实现。 详见测试辅助函数应突出行为意图。

先构造数据和前置条件,再执行被测动作,最后检查结果,能让读者区分条件、事件和承诺。构造-操作-检验与本章后续given-when-then都是组织表达的办法,不要求机械增加三层类或注释。辅助函数可以隐藏重复搭建细节,关键场景差异和结果仍应在测试中清楚。 详见构造操作检验分开表达场景。

围绕常见业务动作建立薄的测试API,可用更少噪声描述场景和期望。书中这种语言是在重构已有难读测试时逐渐提取,而非先造万能测试框架。应保留真实差异并让helper名称对应其责任,出现重复再提取;把所有操作藏在一个泛化入口,未必更易读或更少维护。 详见测试语言应从实际场景演进。

环境控制例按加热器、送风机、制冷器、高温警报、低温警报的固定顺序,以大小写表示开关。HBchL因此表示前三设备中加热和送风开、制冷关,高温警报关、低温警报开。一次比较可聚合相关状态,但顺序与字符含义必须可查,重复H尤其依赖位置;简短不自动等于清楚,失败信息也应便于定位差异。 详见状态编码要保持可解读契约。

实时嵌入式产品可能限制CPU和内存,测试表达辅助未必承担同样约束,因此可选择更直观的构造以便维护。两边都要可靠且整洁,差别是用途和预算。本章五位字符串拼接只是取舍例,未给基准数据;不能据此宣称StringBuffer总更快、生产永远不能拼接,或测试资源成本无需关注。 详见测试与生产可有不同资源预算。

将互不相同的场景塞进同一测试,会让读者猜每组断言的目的,也使前段失败遮住后段。围绕一个场景或契约结论组织测试,必要时用多个断言共同描述其结果。仅把断言包成一个helper并不减少概念数量;强制一个assert也可能制造重复和过度夹具,本章作者最终保留了合理多断言。 详见一个测试应聚焦一个概念。

SerialDate测试从2004年5月31日加一个月得到6月30日,再加一月保留30日;直接加两月则期望7月31日。按目标月上限截断日期,会让两次加一月与一次加两月结果不同。三个行为应分清测试,再补2月28日到3月等遗漏边界。这里是本章期望与代码推导,不是所有日期库的统一约定或本机结果。 详见日期加月可能不满足分步合成。

单元测试足够快时,开发者更容易在小改动后频繁运行,失败与引入它的变化距离更近,便于诊断。应按测试职责安排昂贵依赖和运行层次,而不是只追求毫秒数字或删掉有价值的检查。快速不保证会运行,也不能独立证明测试有效;本章没有给所有项目共同适用的时间阈值。 详见快速反馈依赖可频繁运行。

每个测试建立自身必要前提,才能单独运行或调整顺序,避免第一个失败引发一串虚假的后续失败。共享昂贵夹具可以存在,但要明确隔离、重置与生命周期;不应让某测试的成功执行成为另一个测试隐含的准备步骤。独立性帮助诊断,不等于不需要组合行为的集成验证。 详见独立测试不借用上个测试的状态。

相同输入和已声明条件下,测试应稳定给出同样结论;时间、网络、随机性和外部状态若影响单元契约,应隔离或控制。原书提无网络列车上运行,是强调环境不应任意左右单元反馈;不意味着真实集成测试无需其合法依赖,也不授权将有副作用的测试直接放到生产环境运行。 详见可重复测试要控制必要环境。

测试必须把预期变为可检查条件,由运行结果清楚报告通过或失败。只打印日志、等人看输出或手工对比文件,会增加重复成本并让标准不稳定;可以把必要对比编码为断言。布尔式结论不是说被测业务方法都要返回bool,业务结果类型仍应由其责任决定;自动判定也可能因错误预期而误绿。 详见自足验证要自动判定预期。

在实现之前或同步建立场景与预期,容易及早看见哪些依赖需要控制、哪些行为难以观察,促使设计留下测试接缝。对既有实现补测试仍有价值,不因不符合先后顺序就放弃;本章Timely是TDD式纪律的理由,不能把“先写过测试”当可测性或正确性的充分条件。 详见及时写测试会反馈接口可测性。

原书依据 · 21 处

第10章 类

代码行、函数和测试可以各自清楚,类若把无关责任堆在一起,变化仍会牵动大范围。本章把“短小”解释为责任集中,用SuperDashboard区分窗口与版本变化,用状态/方法的内聚线索发现新的分组,再完整展示素数生成和分页输出的拆分。最后由Sql生成类型和价格源抽象说明:组织的目标是隔离实际变化,降低理解与修改所需范围。

字段位置与调用顺序分别延续成员位置应形成可预期约定和向下阅读使调用层次可追踪;单一职责关注变化理由在类层次有了版本与窗口的具体例子。素数程序靠先建立行为再迭代函数结构逐步转化,Sql则说明开闭原则围绕选定变化扩展,同时以实际变动决定何时拆分。抽象价格源让估值条件可控将第8、9章的接口接缝和可重复测试收束到类的依赖方向,不把替身验证当真实行情或交易验证。

测试需要观察或操作内部时,先问公共行为是否足够表达契约、类是否承担过多责任,再决定是否开放包级或protected接缝。放松可见性会扩大依赖面,不能只为测试方便自动公开所有成员。原文允许必要取舍且称其下策;这不是要求所有测试必须直接调用私有方法,也不是仅用访问修饰符就能获得良好封装。 详见测试可访问性应先审视边界。

五个方法也可能分别处理窗口焦点与版本信息,责任仍然混杂;许多相关操作则可能服务同一概念。可用准确名称和简短职责描述暴露不相干的变化理由。二十五个词、禁用连接词或Manager名称只是诊断线索,不是类设计的语法规则;最终要看真实变化、协作和契约,而非机械计算方法行数。 详见类的大小应按责任理解。

把相互有关的工作放在职责清楚的类中,读者处理一项变化时可只理解直接相关部分,不必穿过庞大的杂项集合。类数量增加可能让导航和协作关系更显眼,仍需通过名称、接口与依赖组织控制成本。抽屉类比是组织目的,不保证任意拆分都不增复杂性,更不是每个方法都要单独成类。 详见模块划分要降低理解的范围。

Stack的size、push、pop围绕元素及栈顶计数协作,使类可作为一个逻辑整体理解。成员被多个方法共同使用是内聚线索,不应为了让每个方法访问所有字段而增加无意义耦合。原文也说最大化内聚通常不可取;计数与元素数量是否始终一致,还需由更新规则与不变量保证。 详见内聚关注状态与行为的整体。

为减少参数把临时变量移到对象字段,虽然方便多个小方法共享,却使更多调用依赖同一状态并可能降低类内聚。若一组方法只围绕这些变量工作,可考虑把它们连同状态放入有明确生命周期的对象。不是一律拆类或提升字段;先判断共享是同一业务概念,还是仅为省参数而让临时状态外溢。 详见局部变量升为字段会扩大生命周期。

PrimePrinter负责执行入口与组装,PrimeGenerator负责产生序列,RowColumnPagePrinter负责按行列分页。这样入口方式、生成算法、显示格式可分别成为变化理由,打印器也不必只服务素数。代码变长可能来自描述性名称与显式边界,不自动说明更复杂或更好;职责仍需结合真实调用和行为核对。 详见素数输出可分成三种变化。

打印器用每页行数乘列数确定页容量,用min限制最后一页的有效索引;同一行后续列按rowsPerPage跨步,体现按列填数。末页可能打印空行,固定行列也需正值约束,否则容量为零会妨碍循环前进。示例没有这些参数校验,不能把教学分页逻辑当任意输入都可用的组件。 详见分页索引应区分边界与布局。

PrimeGenerator先保留2,再只检查奇候选;为已启用的素因子维护不小于候选的最小奇倍数,每次增加两倍该素数,命中即判合数。新因子到其平方时才启用,因为更小的合数已有较小因子可解释。该机制依赖已生成素数和倍数状态,不是简单对所有小于候选的数逐一试除。 详见奇数倍数追踪减少重复筛查。

本章PrimeGenerator把primes数组与倍数列表放在静态字段,generate每次重置再逐步填充;不实例化并不等于没有状态。并发或重入调用可能交错覆盖工作区。n为零时仍写primes[0],负数和整数溢出边界也未处理,故只采算法/职责示例,不宣称其为完整通用安全生成库。 详见工具类静态状态仍然会共享。

Sql轮廓中仅select使用的私有方法,提示可能存在独立职责;本书仍建议若无需相关变化,不必仅为结构偏好立即拆分。当新增能力迫使打开类时,可趁机建立更清楚的边界。这个取舍把改动收益与风险联系起来,不是承诺所有未改代码永远不用维护,也不要求一次拆完所有可能变化。 详见变动证据决定何时拆分责任。

把不同语句生成放进Sql子类,可在既定generate契约内增加新的生成类型,公共帮助职责由Where与ColumnList承担。新增子类仍可能需要选择、注册、组装与测试;基类契约或共享规则改变也会波及现有实现。原文只有方法轮廓且有缺失括号,不能由“封闭类”推断实现风险为零、无缺陷或已验证生成语句安全。 详见扩展点也有契约和组装成本。

Portfolio经构造器接受StockExchange,询价只依赖currentPrice(symbol)这一需要的能力。固定价格替身可让五股乘每股100得到500的预期不受实时行情影响,这检验本地估值协作而非实际交易、行情准确性或资金安全。接口还需明确货币、时点和失败语义;这些未在短例展开。 详见抽象价格源让估值条件可控。

DIP让高层逻辑依赖询价概念而非TokyoStockExchange具体访问细节,低层适配实现同一契约。价值来自把变化隔离到恰当边界,不是给每个具体类机械添加一个接口;若接口把厂商细节照搬出来,改动仍可能向上传播。替身方便注入也不代替真实适配的边界测试和契约维护。 详见依赖抽象要对应稳定业务需要。

原书依据 · 38 处

第11章 系统

类的职责明确之后,系统还要组织对象如何得到创建,以及多个模块共同遵守的基础设施策略。本章从main组装、工厂和依赖注入分开“如何得到对象”与“如何使用对象”,再以EJB历史方案、JDK代理和方面框架讨论持久化等横切关注面。这样做的目的,是让领域逻辑可独立理解和测试,同时让架构随真实需求演进。

构造策略应与运行职责分开延续第10章的依赖方向,工厂分离创建时机与细节说明运行中创建也能维持边界。横切关注面跨越领域边界把职责分析拓展到多个对象共同承担的策略,方面还要声明行为应用位置区分模块表达与代理技术。原书的历史XML和实体示例有明确省略与错误,笔记据其说明设计意图,并分别限定延迟创建、套娃代理和无损一词,未当作可直接部署的项目。

架构方法应回到实际变化与交流:架构演进依赖可替换的边界不排除提前了解范围和风险,可延迟决策应保留行动窗口依赖真实替换余地,领域语言缩短概念到实现的距离则将第9章测试DSL的表达思路扩展到系统领域。标准和框架都要服务可说明的需要,而不是代替需要本身。

getService在使用时硬编码创建MyServiceImpl,让业务对象还承担选型和组装责任,并增加测试中的构造路径。把对象图的建立集中到main或专门组装模块,再将所需能力传入,可让运行逻辑只依赖使用契约。构造并非只能发生在启动一刻;运行中需要创建新对象时,仍可通过明确工厂分离细节。 详见构造策略应与运行职责分开。

首次需要时才构造可避免未使用对象的成本,但getService片段的空值检查和赋值没有同步,不能保证并发下只创建一次或安全发布。构造还可能失败,因此“永不返回null”只在构造正常完成并返回有效实例等条件下成立。延迟是创建时机选择,需说明生命周期、默认实现与失败处理,不能替代依赖边界设计。 详见延迟创建需要失败和并发契约。

订单流程知道何时需要LineItem以及本次业务参数,但不必知道具体如何构建。main创建工厂实现并把接口传给应用;应用调用makeLineItem,具体实现承担创建细节。这样保留业务对时机的控制,并集中构造策略。工厂仍有契约和失败路径,不保证所有对象类型变化都对应用透明。 详见工厂分离创建时机与细节。

业务对象通过构造器或其他约定接收需要的协作者,选哪种实现及如何连接由main或容器决定。对象主动调用JNDI查找虽可隐藏实现类别,仍承担依赖查找,并非完全被动的注入。DI是IoC在依赖管理的应用,不要求必须有大型容器或XML;关键是组装责任与使用职责的方向。 详见依赖注入把组装交给外部。

依赖可由外部注入,同时选择立即、按需或经工厂取得;这是不同决策。原书泛称多数DI容器按需创建,不宜当通则。Spring ApplicationContext默认预创建单例,显式延迟的bean若是非延迟单例的依赖,也可能在启动时创建。应查看具体容器、作用域和依赖关系,而非从“用了DI”推断启动成本已消失。 详见注入方式不决定创建时机。

EJB2 Bank例把业务数据与EntityBean生命周期、JNDI查找、容器创建和部署描述关联起来。若测试业务也必须满足这些设施前提,隔离测试与迁移会更困难。把纯规则与适配职责分开,可减少需要模拟的环境。例中有包名/导入与省略实现缺口,只用于历史耦合说明,不是可运行配置,也不证明所有容器设计都同样有害。 详见基础设施侵入会扩大测试前提。

持久化、事务和安全等策略可能需要在多个领域对象的操作上保持一致,只按领域类拆分就会把相同规则散落各处。横切关注面讨论如何在保留领域模块边界的同时集中表达这种策略。不是凡重复代码都要用AOP;先识别一致策略及其应用位置,再选择组合、拦截或其他合适机制。 详见横切关注面跨越领域边界。

AOP不仅是替某个对象包一层调用,还要以可管理方式说明哪些位置应用何种横切行为。框架可以免去逐处手改源码,但增加的持久化、事务或安全行为仍会改变运行语义,应检查匹配范围、顺序和失败。原文“无损”脚注指不手工改源码,不能读成没有副作用或自动保持全部业务行为。 详见方面还要声明行为应用位置。

JDK动态代理实现指定接口,接口调用被转交InvocationHandler.invoke,处理器据Method和参数执行额外工作或委托。Bank例在读前装载账号、写后保存,展示调用边界附加行为。按方法名分支只是教学片段,不能代表所有重载、Object方法和异常都已正确处理;完整代理要维护真实接口契约。 详见动态代理将调用交给处理器。

示例setAccounts先修改内存对象再写数据库;若持久化失败,片段没有补偿或事务说明。getAccounts每次加载也改变内部状态,返回集合是否可变另需约定。代理只提供截获入口,不能因用了代理就推断内存与数据库原子一致、资源已关闭或所有调用都经过同一边界。 详见代理包装不自动提供事务一致性。

app.xml片段把DataSource注入DAO、再把DAO注入Bank,明确的是依赖连接。原书图11-3进一步用俄罗斯套娃说明装饰包装的意图,但该XML没有给出同接口代理或拦截配置,不能单凭属性引用证明图中透明多层代理已建立。应区分依赖图、调用链与实际包装机制,按实现和配置确认。 详见对象注入不等于装饰器套接。

EJB3版本通过注解表达实体标识、嵌入地址及账号关系,比实现一组容器回调更少侵入普通业务方法。但注解承载的持久化语义仍是依赖,不会因代码短就消失。Bank.addAccount同时设置账号反向引用并加入集合,而setAccounts只替换集合,二者约束并不自动等价;示例不构成所有关联、加载和生命周期都已验证的实现。 详见声明映射仍然保留基础设施契约。

把领域逻辑和基础设施关注面分开,使先交付有限需求、再随证据增加能力更可行,避免过早把所有细节锁定。原书也明确仍要预期范围、目标、进度和总体结构;反对BDUF不等于毫无设计。关键风险和难以逆转的约束需事先了解,持续测试能反馈变化,不能保证任何架构都可低成本根本重写。 详见架构演进依赖可替换的边界。

模块边界让局部专家掌握相应决策,并在更多用户反馈和实施信息出现后选择方案。延迟的收益来自减少无依据假设,不是所有事都等最后一刻:要保留实现、验证和协调时间,识别不可逆成本。没有替换余地却不作决定只会转成风险;授权也不免去跨边界契约的协调。 详见可延迟决策应保留行动窗口。

共同标准可能帮助复用组件、招聘有经验的人和系统互通,也可能带来不适合当前需求的复杂性。不能只因EJB2是标准就采用整套架构,应具体比较业务价值、集成契约和维护负担。这里针对可选架构方案的判断,不表示已适用的外部强制要求可由团队随意省略。 详见标准的价值要落到实际需要。

DSL可以是小脚本,也可以是用通用语言构建的API;用领域专家的词汇表达规则,能让实现意图更接近讨论中的概念,减少翻译误会。它仍需要明确语义、有效工具和可验证的行为,不能仅因代码读似散文就保证专家能独立使用或没有缺陷。抽象层越高,也越要能追踪到其实际执行边界。 详见领域语言缩短概念到实现的距离。

原书依据 · 22 处

第12章 迭进

本章把前面各层次的设计办法放回持续修改的节奏:先让预期有可运行的检查,再在小步变更中消除重复、表达意图,并控制无价值的结构数量。四条规则按优先级取舍,避免为了少一个方法而挤乱意图,也避免为了短小而为每个类机械增加接口。

简单设计规则有优先顺序在这里取得四条完整表述和顺序依据,先建立行为再迭代函数结构说明如何将这些准则用于日常变更。size/isEmpty展示同一事实不宜双份维护,图像例提醒抽取重复不会消除原有缺陷;模板方法固定步骤开放差异则将共同算法与地区差异分离,承接第3章的共享步骤应显式表达差异。

表达力连接名称、模式词汇和测试可作为行为实例文档,以帮助没有作者即时上下文的维护者。最终减少实体数量服从更高目标为第10章短小类补上节制条件:保留实际需要的边界,去掉缺乏职责的间接层。规则提供观察方向,仍需经验、行为证据和具体约束作判断。

为了给类建立可控条件,测试会迫使人看见难以替换的外部依赖、混杂责任和不易观察的结果,推动短小职责与注入边界。这个反馈只有在测试有效、围绕行为编写并持续使用时才有价值;“可测试”不自动推出低耦合,“全部通过”也只证明实际断言涉及的行为,不能由此宣称系统全部已验证。 详见测试反馈能暴露设计依赖。

集合的计数与“是否为空”若各自存一份可变状态,每次变更都要保持两者一致。让isEmpty根据size是否为零得出结果,可用同一事实来源减少同步维护。它仍依赖size契约、计算成本与并发语义;某些结构的size可能很昂贵,不能机械改写所有容器或认为一次调用就形成并发快照。 详见同一状态宜避免双份维护。

scale与rotate的dispose、gc、赋值三步移到replaceImage,集中共同更新流程,却没有证明资源和并发策略已正确。rotate仍同步而scale不加同一锁;图像创建、旧图释放的失败和别名引用都需单独考虑。System.gc只是回收建议,不能替代确定的资源生命周期,也不能保证旧对象立刻回收。本例是结构重组,不是完备图像组件。 详见抽取重复不会消除原有缺陷。

VacationPolicy.accrueVacation先计算基础时数,再调整最低要求,最后应用到薪资记录;公共算法通过alterForLegalMinimums钩子让地区子类提供差异。这样共享顺序不必在各分支复制。例中算法体皆省略,地区标签不是实际法规或已验证计算;入口也未声明final,不能据此说Java语言已禁止子类重写整个顺序。 详见模板方法固定步骤开放差异。

Command、Visitor等共同术语可帮助维护者借已有知识识别设计角色,减少从零解读。但名称必须对应实际契约与协作;把类后缀改成模式名并不会建立模式,也不能假定所有读者已理解。表达力来自名称、职责、结构和行为一致,必要时仍需解释领域差异。 详见模式名称要与真实角色相符。

好的测试把前提、动作和期望放在一起,让后来者从具体例子理解类的用途与边界。它通常只展示部分输入和运行条件,需与接口契约和领域说明相配合,不能把几例当穷尽规范。修改时应核对期望是否仍是想要的行为,不能为恢复绿灯随意改断言,也不能用陈旧测试误导维护者。 详见测试可作为行为实例文档。

一律为每个类创建接口,或把字段和行为都强拆,可能增加导航和维护成本而没有隔离真实变化。简单设计把减少类/方法放在测试、去重复与表达意图之后;应删除无用层次,也保留有价值边界。目标不是追求最少文件或最短行数,而是在行为有依据、意图清楚的前提下避免教条式结构。 详见减少实体数量服从更高目标。

原书依据 · 19 处

第13章 并发编程

前几章在默认顺序下组织责任,本章将执行时机也作为设计变量。并发可以重叠等待或组织独立工作,却使共享状态出现交错、可见性和进度问题;因此要先界定可共享的数据与不变量,再选择库、执行模型和协调边界。原书给的是概览,附录A还将展开模型、锁和测试细节。

复合自增可产生重复编号说明一行代码不等于原子操作;请求局部引用未必指向独占对象与数据副本减少共享仍需边界则把是否共享追到真实对象及可达状态。并发协调有独立变化理由,回连单一职责关注变化理由。表13-1的三种协调工具分别有线程所有权、许可和一次性计数契约,表13-2又把互斥与饥饿、死锁、活锁分开,不能仅凭使用线程安全类就宣称整个流程安全。

生产消费、读写和多资源竞争提供三种观察模型。多个同步方法不等于整段原子与同步范围应覆盖完整不变量说明锁必须围绕业务动作而非方法数或代码行数划界;关闭协议必须唤醒等待者进一步提醒正常运行和终止是不同路径。最后用可插拔环境、多平台、多负载和调度扰动增加暴露机会,并保存偶发失败证据。它们延续第9章的可控条件与自足判定,重复通过仍不等于穷尽所有交错。

并发把任务做什么与何时获得执行机会分开,可重叠网络等待或组织独立工作;并行则还需要可用处理资源让工作同时进行。吞吐、延迟与结构收益取决于瓶颈、任务独立性和额外开销。原文“只有分享等待才改善”的说法过窄,独立CPU任务也可能受益于多核;增加线程不自动带来加速。 详见并发分开任务目的与执行时机。

两个线程共享lastIdUsed时,++不等于不可分割的读取、递增和写回。两线程都读42再写43,可各返回43并丢一次更新,违反需要唯一连续结果的意图。应按所需不变量选择原子更新或同一互斥边界;单字段原子读写也不自动保护整个动作。原书具体路径数依赖其模型,不能当所有JVM的通用调度数量。 详见复合自增可产生重复编号。

保护共享字段需要所有相关访问遵守一致同步协议,入口越散,越容易遗漏某个写入或读改写序列。封装状态并限制访问位置,可使保护不变量的责任更清楚。private只是访问范围,不是线程安全;多个不同锁或未遵守协议的代码仍可能互相干扰,不能按临界区数量少就判正确。 详见共享状态的访问面应受控。

让线程处理自己的数据副本,最后在明确阶段合并结果,可减少对同一可变状态的争用。副本需要包含应隔离的可变子对象,浅复制或共享底层缓存未必做到独立;合并也要有顺序、冲突和可见性约定。额外分配与回收可能被减少锁等待抵消,但须针对实际负载衡量,不能预设总会更快。 详见数据副本减少共享仍需边界。

doGet/doPost的参数与局部变量可以引用共享服务、连接或会话数据。只有可变对象的可达关系确实隔离,且没有公共资源交互时,线程才可按独立工作者处理。Servlet容器可并发调用服务方法,不会给每次请求一台独立虚拟机;必须识别实例字段、静态状态和外部资源的共享。 详见请求局部引用未必指向独占对象。

ConcurrentHashMap允许并发读写并提供特定原子复合方法,但把几次get/put任意组合并不会自动成为同一事务。容器安全也不等于值对象内部安全或遍历获得全局快照。原书称其几乎总胜过HashMap没有通用基准依据,应先满足并发语义,再在同等正确前提和实际负载下比较性能。 详见并发容器提供有边界的原子能力。

表13-1用ReentrantLock说明锁获取与释放可以写在不同方法;这要求持锁的仍是同一线程,并按次数配对释放。可重入表示已持锁线程能再次进入,不是可由另一线程随意解锁。实际代码须确保失败路径也释放,分散方法还会增加追踪生命周期的成本。 详见显式可重入锁仍归线程所有。

Semaphore维护可用许可计数,获取可能等待,释放增加许可,可用于控制有限资源的并发访问量。它不同于互斥锁的单一线程所有权,不能仅凭许可数就证明被保护资源的数据结构安全;释放还需对应实际归还,避免把容量凭空放大。图表把它叫有计数器的锁是简写。 详见信号量用许可限制同时进入数。

CountDownLatch让await等到计数降为零,再允许等待者继续,适合一次性的共同起点或等待多项工作完成。countDown调用者无须等其他人,也不保证获释线程物理同时运行;计数不能重置。它不是互斥锁,零之后后续await可直接通过,必须由正确的事件计数表达条件。 详见倒计时门闩协调完成条件。

有限连接、缓冲空间等资源会约束并发;互斥防止同一保护区域被同时操作,解决的是冲突访问。线程饥饿是长期得不到执行或资源,死锁是互相等待不能前进,活锁则可能不断响应却没有有用进展。程序没有数据竞争不等于不会卡住,诊断要同时观察不变量与进度。 详见互斥与活性问题要分开判断。

生产者把工作放进队列,消费者取出处理,使两种活动按自己的节奏协作。有界空间让生产过快时必须等待、拒绝或采用明确策略,队列为空时消费者也需要等待或结束规则。模型不自动保证交付一次、任务完成或平静关闭;错误与终止信号是队列协议的一部分。 详见有界队列连接生产与消费速率。

读者需要稳定可读的状态,作者更新时要防止读到不满足契约的中间状态。过度优待读者可能延迟作者,作者长期占有也会阻塞读者;需结合访问比例、临界区和公平策略平衡吞吐与饥饿。不能只因读多写少就断言读写锁总比其他方案好,还需判断实际数据共享方式。 详见读写协调兼顾一致性与进度。

哲学家各持一把叉子再等另一把,可能形成所有人互相等待的环;若大家同步退让又同步重试,也可能持续动作却无进展。把线程与资源对应后,应设计一致的获取协议与释放路径。原书在此引出模型而未展开解决算法,不能声称它已给出无死锁或公平性证明。 详见多资源获取需要统一协调。

检查条件再执行操作若由两个独立同步方法组成,其间可被其他线程改变共享状态。可由客户端把全部调用纳入同一锁,或让服务端提供保护整个业务动作的入口,也可由适配层集中保护。关键是相关参与者使用同一有效协议;仅包一个私有锁而其他入口绕过它,不能建立整体原子性。 详见多个同步方法不等于整段原子。

保护不足会留下竞争窗口,保护过宽则可能把无关工作或等待也串行化,增加争用。应先找出必须一起观察或修改的状态,再把完整动作放在同一同步协议内,移出不需要共享保护的工作。最小不是按行数剪碎,锁开销也随实现与竞争而变,不能为了性能去掉正确性需要的边界。 详见同步范围应覆盖完整不变量。

父线程等所有子线程退出,但生产者先结束、消费者仍等永不再来的数据时,整个关闭过程会卡住。停止标志只有等待线程能及时观察才有效,应明确阻塞等待如何结束、何时停止接收工作、如何报告完成及释放资源。正常任务能完成不证明停止路径正确,关闭应作为独立场景尽早设计。 详见关闭协议必须唤醒等待者。

并发问题只在少数交错出现,后续重复运行通过不能抹掉已有失败。记录当时负载、配置和失败状态并追踪原因,有助于区分共享状态缺陷、测试前提或环境因素。不要未经调查归咎运气,也不能反过来认定所有不稳定测试都是线程缺陷;归因需要可核验线索。 详见偶发失败应保留为调查证据。

先在线程之外验证纯业务对象,再用可插拔的执行配置与快慢替身测试并发协调,可减少同时追踪两类缺陷的困难。允许调整线程数、迭代次数和依赖延迟,观察吞吐与资源使用;调参只改变实验条件,不能用一个最优数字代表所有负载,也不能由业务测试通过推断协调安全。 详见并发测试宜分离业务与调度。

增加可运行线程、改变负载并覆盖实际目标平台,可能让原先少见的交错发生,暴露遗漏的保护或进度问题。线程数超过核数不是必现错误的技巧,更不是生产容量的通用配置。书中OS X与XP的差异是一次已知错误程序的教学经历,不足以给平台排名;未失败仍不证明所有交错正确。 详见调度多样性增加暴露机会。

Thread.yield只是向调度器表达愿意让步,可能被忽略;在synchronized方法内调用它不会因此把监视器交给其他线程。sleep也不释放持有的监视器,wait则有持锁、释放和重新竞争等不同语义。原文Object.sleep/yield/priority名称有误,不能当Java调用清单照抄;扰动手段须按真实API和目的选择。 详见让步提示不释放监视器。

可在选定接缝设置jiggle钩子,让测试选择不动作、延迟或让步,多次探索执行顺序,同时保留正常版本。应记录配置和失败条件,确认钩子没有引入错误的业务副作用或留下不必要生产开销。随机千次不穷尽路径;ThreadJiglePoint拼写不一致及工具ConTest只为原书例,不当已运行或当期可用保证。 详见调度扰动测试要可配置可追索。

原书依据 · 42 处

第14章 逐步改进

本章用自写命令行解析器Args追踪从可运行草稿到职责分离的变化。全章从最终接口倒叙到草稿,再完整追踪值表示、类型行为、索引、输入消费和错误职责的逐步迁移;中间快照与测试代码均已读。案例展示结构如何变化,也暴露需要明确确认的公开契约变化,不能把所有版本都视为行为相同。

范式把字符名映射到类型行为,共享迭代器把值消费交给类型让布尔与取下一词的类型有所分工;参数出现与默认值是不同事实解释has与getter分别回答的问题。错误对象集中承载失败上下文把错误码、参数名和文案放在一起,类型扩展仍需维护协调位置则说明多态后的新类型仍有若干接线触点。最终结构是先建立行为再迭代函数结构的案例,而非要求第一次就写出同样组织。

Args用逗号分隔的范式说明参数名与类型:空尾部选布尔、星号选字符串、井号选整数,另有双井号与字符串数组标记。parseSchemaElement据此建立字符到ArgumentMarshaler的映射,后续扫描不必再按类型写完整分支。它是本书自定义协议,double/数组实现未给出,不能从标记就推断这些类型的全部语法和错误行为。 详见解析范式把标识映射到行为。

parseSchema在trim之前判断长度,纯空白元素trim后仍会进入charAt(0),可能抛出未包装的索引异常。重复参数名则被Map.put覆盖,原例没有显式拒绝。由此不能仅凭接口宣称所有范式错误都转换成ArgsException;应先定义空元素、重复名和允许字符的契约,再让检查顺序覆盖它。 详见输入校验顺序影响边界行为。

Args扫描以横线开头的词,把其中字符交给各marshaler;需要值的实现推进同一个迭代器取得下一词,布尔实现则不消费下一词。遇到首个普通词时previous回退并停止,nextArgument可指出未消费位置。这个协议需明确组合标识、负值和普通位置参数的边界,不能将其当任意CLI语法都支持的解析器。 详见共享迭代器把值消费交给类型。

has查询argsFound,getBoolean/getInt/getString则取得各类型值。没有出现的已声明整数可读为0,布尔可为false,因此只看值不能辨别用户是否明确传入。应用若需要区分默认与显式输入,必须使用出现记录等明确契约;构造失败时则不能把部分记录当成功解析结果。 详见参数出现与默认值是不同事实。

StringArgumentMarshaler取下一个词,耗尽时报告MISSING_STRING;IntegerArgumentMarshaler先取词,再用parseInt,分别将耗尽和数值格式失败转成不同错误码。这样错误可保留“缺一个值”与“给了不合法值”的区别。下一词若看似另一个选项,本例仍可能先被消费为值,不能凭异常分类假定已处理所有标识歧义。 详见类型专用解析分开缺失与非法值。

三个静态getValue先判断marshaler类型,null或不匹配就返回false、空串或0。这个便利同时让未声明参数、调用了错误getter与某些合法默认值难区分。若接口要求调用者按范式取值,应明示这种责任;若希望误用能及时暴露,则需另定类型错误契约。本例没有凭getter自动报告所有误用。 详见宽松取值可能掩盖调用类型错误。

ArgsException组合错误码、参数标识和原始词,并在errorMessage中集中生成面向人的描述;解析层可补充当时正处理的参数名再抛出。这样类型解析无需知道所有展示文案。集中不自动完整:默认OK会得到TILT文本,纯message构造器未设置错误码,而errorMessage也不读取message,调用者需明确用哪一种错误表示。 详见错误对象集中承载失败上下文。

新增Args类型可增加ArgumentMarshaler实现,但还需添加范式分派、公开getter,必要时增错误码与文案。多态集中类型行为,未让协调层对任何新类型完全封闭。应把实际扩展步骤列清楚,检查每个触点的契约和测试,不因有接口就宣称增加功能零修改、零风险。 详见类型扩展仍需维护协调位置。

Args草稿用valid、errorCode、出错参数及异常共同表达解析失败:类型解析先写字段再抛内部ArgsException,parse捕获后返回valid。空catch在这里不是自动意味着错误丢失,但原因被放在共享字段而非异常本身,正确性依赖各路径都先设置一致状态。范式ParseException又直接外抛,调用方必须理解两套失败契约,不能只看构造正常返回。 详见失败状态与控制转移需要一致。

草稿为Boolean、String和Integer各维护一张Map,并分别在范式选择、输入转换和getter中识别类型。新增类型时同一维度在多处同步扩展,易留下不一致。后续ArgumentMarshaler的动机是把同类行为与状态聚到一起,而不是只减少几行相似文字;仍要保留协调层需要知道的类型选择。 详见类型维度的重复会扩散修改点。

Boolean早期版本每遇见一个已知标识就增加numberOfArguments;后续版本cardinality改用argsFound集合大小。同一标识重复出现时,前者计出现次数、后者计不同标识数,二者语义并不相同。比较版本时要先定义“参数数”指哪一种,再决定这是修复还是契约改变,不能仅凭方法同名认定行为保持。 详见计数接口要说明统计的对象。

Boolean/String版本的setArgument对字符串类型调用setStringArg后仍返回true,即使下层因缺少值已把valid设为false;于是上层仍将其加入argsFound。这个布尔实质表示识别到类型,名称却容易让人理解为值已设置。应按方法责任选择正面的真实结果语义,并把正常未执行、成功动作和失败区分;调用者不能据一个模糊true记录成功。 详见设置结果不能只表示识别类型。

将Boolean值换成ArgumentMarshaler,不只改Map类型,还要调整初始化、设置和读取的位置。先列出这些触点、保持对外行为,再逐步移动职责,可缩小每次变化的解释范围。增加暂未使用的类轮廓是该案例的过渡手段,不是所有重构都需如此;轮廓能编译或没有明显副作用,也不证明未来实现正确。 详见替换表示时应先枚举契约触点。

falseIfNull(booleanArgs.get(arg).getBoolean())先求参数表达式,再进入falseIfNull。Map未找到标识时,null上的getBoolean已抛异常,外层helper来不及兜底。把检查放到真正可能为null的ArgumentMarshaler上,再读取其值,才能保留未知布尔参数返回false的旧约定。包装名称并不会改变求值顺序。 详见包装调用前的解引用仍会先失败。

草稿比较揭示,问题不只在字段多:失败状态与控制转移需要一致展示valid、错误码和异常分担契约时的隐式配合,设置结果不能只表示识别类型则说明一个true可能只是类型被认出,并非值已设置。不同版本还改变了cardinality的统计对象,比较时应显式区分这些语义。

暂停扩功能后,作者从三处重复的类型责任发现ArgumentMarshaler,并先迁移Boolean。替换表示时应先枚举契约触点说明小步移动的依据,包装调用前的解引用仍会先失败展示即使只改几行也会让原有默认契约回归。自动化测试在叙述中为反馈入口,笔记保留实际代码推导与作者报告的区别。

作者先把Boolean、String和Integer的状态与访问暂放ArgumentMarshaler基类,使调用先统一到同一表示,再将对应状态和行为逐个下移到派生类。临时基类承担多类型数据是迁移接缝,不是目标设计的高内聚证明。应说明过渡结束条件,并在每次移动后检查既有外部契约,避免把脚手架永久化。 详见迁移中的集中状态只是过渡。

迁移中用Object get让各类型共享调用形状,读取方则需转回Boolean、String或Integer。接口更统一,编译期可表达的类型关系却减弱,错误可能移到运行时转换或拆箱。基类暂返回null虽然可编译也不符合原值契约,需由真实派生实现承接;不能只以编译通过作为行为迁移成功。 详见统一返回类型会移动类型责任。

新增marshalers Map时,先把同一个新marshaler放进旧类型Map与新Map,再逐步迁移查找、设置、读取,最后去掉旧索引。若两边各建一个状态对象,写旧读新就会失配;这段迁移依赖的是共享同一实例,而不是无条件复制数据。临时双写需明确删除时机,防止新旧索引长期漂移。 详见双写迁移需保持同一对象身份。

统一Map之后,原先用错类型调用getBoolean会查不到旧类型Map而返回false,如今可能取得其他marshaler并在强转时失败。作者到这一步才运行到FitNesse中约束该行为的验收测试,说明一直绿的单元测试没有覆盖这条契约。应按本次改动运行相关层次与边界场景,而非把某个套件的通过扩大为全部行为未变。 详见局部测试通过不代表契约已覆盖。

Integer marshaler知道数值转换是否失败,参数值消费层知道缺了哪个值,上层setArgument知道当前标识。把valid和参数名的共同处理收拢,可减少各类型重复写字段,同时保留低层原因。重组要检查每条失败路径是否仍保有正确码、原词和标识,不能集中catch后把不同原因都改成一种或重复覆盖。 详见错误上下文可按责任逐层补充。

首次重构已把三张Map统一,并把值状态放进各marshaler,但Args仍保留类型判断、输入游标和多处错误字段,set方法还按类型消费值。结构改善是实在的,剩余变化点也应明确列出,决定下一步移到哪层;不能以增加类和接口的数量代替职责已经完整分离的结论。 详见初步抽象要检查剩余职责。

String和Integer沿同样触点迁移后,迁移中的集中状态只是过渡说明先聚到基类再下移只是控制变化的路径;统一返回类型会移动类型责任指出Object返回值需要调用方转换,类型安全责任没有凭空消失。随后双写迁移需保持同一对象身份用同一实例把旧索引与新索引接起来,再逐处删除旧入口。

统一索引暴露了验收测试中已有、单元测试却没约束的错误getter默认行为,形成局部测试通过不代表契约已覆盖的具体反例。错误上下文可按责任逐层补充收拢部分重复处理,但初步抽象要检查剩余职责仍列明首次快照留下的类型分派、消费和错误状态;下一步继续处理这些实际责任,而不是凭类数量宣布重构结束。

旧setArgument用类型链末尾的else表示未知参数。准备让所有已知类型都统一调用m.set之前,先把m为null的未知条件独立处理,才能避免删除类型链时连失败语义一起丢掉。接口派发替代的是已知类型间的选择,不替代查找失败和参数合法性检查;重构顺序应保护这些不同责任。 详见先分离错误分支再统一派发。

各marshaler都接收“从余下参数流设置本值”的操作,因此Boolean也可实现接收Iterator的set,只是不消费后续词;String和Integer则消费并转换。未使用某个参数不必然错误,关键是接口对不同实现承诺相同角色。数组与游标合为迭代器是按协议归并,不应推广为所有多参数函数都必须包装成一个参数。 详见统一签名应表达共同调用协议。

double例先检查42.3的正常解析、出现记录和容限,再检查不可解析词与缺少值,连同错误码、标识和文案,才能约束新增类型的外部行为。成功用例通过不覆盖失败边界,已展示测试也未穷尽重复、特殊数值或全部组合。早期invalidDouble用getInt读默认值不能单独证明double值正确,仍须按真实契约选择判据。 详见新增类型要覆盖成功与失败。

早期Args构造后允许调用isValid、has和errorMessage检查失败;后期直接在构造过程中抛ArgsException,调用者无法取得正常构造结果。未知标识也从收集多个转向首次失败,测试只期待第一个x。这是公开失败协议的变化,调用端和相关测试必须一起迁移;结构改善不能自动作为语义等价证明。 详见状态查询改抛异常会改变契约。

Args负责解析,把错误格式化移出可减少混杂;将便利用文案放在ArgsException中,使普通调用者马上可读错误,也让有需要的调用者从错误码和参数自行展示。作者明确称这是折衷,不是所有异常都应内置最终用户文案。仍需保持错误枚举和消息分支一致、说明默认状态及语言需求,不能把移到独立文件当全部错误契约已完备。 详见文案归属可以是明确的折衷。

后半段通过迭代器把输入消费交给类型实现,并先分离错误分支再统一派发,最后将相同分支收拢成m.set。统一签名应表达共同调用协议解释Boolean为什么可以接收但不消费迭代器,避免把“减少参数”当脱离责任的目标。新double类型再用新增类型要覆盖成功与失败核对成功、非法与缺失三种外部行为。

错误职责迁出后,状态查询改抛异常会改变契约标记了isValid到构造异常、收集未知项到首错的公开变化;文案归属可以是明确的折衷说明异常既保存结构化信息又提供便利用文本的取舍。末段快照与章首最终版仍有差异,作者把最后整理留给练习;笔记没有声称那些未展示的小步骤都已逐一验证。小结回到每次修改留下局部改善:及时整理可限制隐性依赖的累积,但规则仍要受行为契约和有效测试约束。

原书依据 · 77 处

第15章 JUnit内幕

上一章展示大型逐步整理,本章把观察缩到JUnit的一段比较消息代码。它先找共同前缀和不重叠的共同后缀,再给两侧差异加括号,按上下文长度保留附近内容并省略其余部分。完整测试清单让空差异、插删、相等和null等行为可见;作者的覆盖报告说明其当时的检查范围,不构成本轮执行结果或所有输入都正确的证明。

偏移编码会增加边界推理成本是这次整理的关键:原后缀值比真实长度多一,名称与使用约定不一致,才使多个地方需要补偿。改变索引约定要同步边界使用将从尾取字符、重叠条件和substring边界一起解释,空片段契约可消除无效分支则说明简化条件需要组成函数在零长度时仍有明确结果。

名称和抽取仍以责任为依据。正面条件仍须准确表达责任与前面的方法名称应对应实际业务责任衔接:入口的结果是格式化比较消息,条件只说明能否进行差异展示。时序依赖可以由结构维护把必须先求前缀的约束放到组合操作里,最终分析与合成可按职责分层让边界分析和输出构造可分别阅读。部分抽取又被内联、字段又回到局部,体现迭代中的可回退判断;public入口改名也必须同步其调用边界,书中旧测试清单不能直接当最终版已运行验证。

ComparisonCompactor把共同前缀和后缀附近的少量文字留作上下文,用方括号突出中间差异,省略号提示还有未展示的共同部分。它生成的是可读比较消息,不是可还原的数据压缩,也不是逐个最小编辑的完整diff。contextLength控制保留长度,示例没有完整参数校验,不能据它推断任意负值也有效。 详见比较消息可压缩共同上下文。

一个字符串比另一个多出字符时,较短一侧可用[]对应缺失位置;例如ab与abc展示ab[]和ab[c]。共同前后缀不能重叠,否则会把插入或删除吞掉。测试同时覆盖开头、结尾和重叠匹配,帮助明确两侧如何对齐;不应把空差异片段当失败或强行塞入占位字符。 详见差异区间可以是空片段。

原版fSuffix存的是共同后缀长度加一:从末尾索引回扫,结果用expected.length减最后未匹配索引。因此后缀为空时它也为1,截取差异终点才要再加一。若仅看变量名把它当真实长度,就容易在循环、substring和条件判断处发生偏一错误;应先写出表示约定,再同步整理各个使用点。 详见偏移编码会增加边界推理成本。

把null、相等等条件封装并用canBeCompacted表达“输入可做差异展示”,有助于在入口看见决策理由。但该布尔描述的是能力条件,不是已执行压缩,更不是调用者应返回。真正入口负责格式化比较消息,即使无需压缩也返回消息,所以名称应覆盖这个业务结果;条件正面只是表达手段,不是改对责任的充分条件。 详见正面条件仍须准确表达责任。

后缀搜索必须知道前缀边界,才能避免两端匹配互相重叠。可把前缀作为显式参数,使数据依赖可见;也可让一个语义完整的findCommonPrefixAndSuffix先求前缀再求后缀,让外部无须记调用顺序。取舍要看接口是否说清必要关系,不能只因多一个参数就判坏,或以合并函数名代替真实顺序检查。 详见时序依赖可以由结构维护。

把后缀从“长度加一”改成从零计数的真实长度,需要一起调整从尾取字符的-1、重叠判断的<=及差异substring终点。只改字段名或初值会让消费者仍按旧含义解释。可用长度/半开区间等明确约定逐处核对,并保留开头、结尾、空片段和长度不等的测试;本章未展示的后续微调不能当已经逐步验证。 详见改变索引约定要同步边界使用。

当共同前缀或后缀长度为零时,相应上下文函数若仍返回正确的空串,就可统一拼接,而不在每处额外判断是否非空。原后缀条件因偏移编码始终满足,改约定后才显出它未提供必要保护。移除条件应先确认每个组成函数在边界上都有定义,不能把测试通过泛化为任意条件都可删除。 详见空片段契约可消除无效分支。

最终例先分析共同前后缀边界,再由startingContext、delta、endingContext等函数合成消息;读者可分开理解“哪里不同”和“怎样展示”。同一共同上下文可取自expected,而差异片段需分别取两侧。命名与层次应对应实际数据,不因函数拆得多就更清楚;最终版也重新内联了部分先前抽取。 详见分析与合成可按职责分层。

原书依据 · 18 处

第16章 重构SerialDate

本章以SerialDate为对象,把日期算法、类型、构造和兼容问题放进同一次整理。首先补测试暴露严格前后星期、最近星期等边界;同时区分原契约的缺陷、新增的解析偏好和未决缩写,避免把作者希望的全部行为都称为旧代码错误。随后才围绕日期本身与Spreadsheet实现的责任重新组织。完整原始、测试和最终源码在附录B,正文已读不代替后续附录阅读。

实现能力可随创建策略提供将日期范围与具体实例的选择移到同一构造边界,静态可替换工厂仍有全局状态说明该示例仍保留共享配置。枚举缩窄取值仍需边界转换让月份、星期和区间语义可区分;行为宜靠近其解释的数据概念进一步把解析、显示和季度计算放到相关符号附近。序列兼容、默认构造器和final各有语言规则,笔记据官方资料限定作者的强烈偏好,未把一次风格选择当普遍规定。

日期运算通过加月应先求目标再裁剪日期明确跨年与月末,返回新值的方法应显露结果用途则把方法责任落到新日期上。上移算法前须找隐含实现假设揭示序号零的星期如何影响公共算法,区间成员资格可由枚举承载把开闭边界和排序端点讲清楚。每次移动都需要看契约与调用范围:仅测试调用不代表公开API无用限制删除结论,覆盖率变化需要看分母与内容限制百分比结论。文中测试和覆盖数均为作者报告,本轮未运行JCommon或替换任何真实日期库。

作者新增测试后,有些失败暴露周几边界算法的问题,有些则只是他希望日期名称不区分大小写,缩写tues/thurs甚至尚未决定。重构前应明确哪些行为由已有契约要求、哪些是新需求,再分别处理,不能把所有新测试的红灯都叫原实现缺陷。提高覆盖也不证明未决规范已被解决。 详见期望变化应与缺陷修复分开。

“下一个周六”若约定严格在基准之后,同为周六时应偏移七天,不能返回当天;前一个同理偏移负七天。算法以目标星期减当前星期得偏移,再在非正或非负边界修正,等号决定是否包含当天。名称本身未足够定义所有API,应将严格前后与含当天的约定写入契约。 详见严格前后星期要排除当天。

目标星期与当前星期之差先加七再取余,得到0到6的向前距离;大于3则减七,得到更近的向后偏移,否则向前走。按一周七天的编号约定,同日偏移零,最近距离不超过三天。解释变量名可把“本周差”“未来差”和“过去差”分别说清,不应依赖未给出的任意编号或日期系统也适用。 详见最近星期可用循环偏移选择。

Month、Day等枚举用类型区分符号,避免把任意整数当月份或星期,也让相关操作更易归属。外部整数仍须在make/fromInt处校验,引用仍可能为null,旧数字接口和序列化边界也要迁移。不能因内部参数改为枚举,就认定系统所有无效输入检查均可删除或IDE能找到全部外部调用。 详见枚举缩窄取值仍需边界转换。

serialVersionUID参与对象流与本地类的版本匹配;默认值对类细节敏感,删除显式声明可能破坏旧数据读取。原书倾向让不兼容尽快失败,审读者与JDK文档则强调显式控制以避免小改动的意外失效。应先决定是否支持跨版本读取与迁移,再选择策略;相同UID不证明全部状态语义兼容,默认UID也非每次源码改动必变化。 详见序列版本号需要兼容策略。

抽象DayDate不宜固定某种SpreadsheetDate的起点与年份限制,调用方却在创建日期前需要知道支持范围。DayDateFactory同时提供makeDate与实现的最小/最大年份,把选择与能力查询集中到构造边界。工厂仍应让报告范围与实际创建契约一致,不能只把常量挪文件就消除实现依赖。 详见实现能力可随创建策略提供。

DayDateFactory用静态字段保存当前工厂,静态方法转发到其抽象实现,setInstance允许更换。它便于集中选型,同时带来全局配置、测试互扰和并发替换的责任;所示代码未检查null或同步。不能仅因使用抽象工厂就等同每个调用方的独立注入,也不能由作者命名推断已实现标准装饰器结构或并发安全。 详见静态可替换工厂仍有全局状态。

只有类没有声明任何构造器时,Java才隐式提供默认构造器,其访问级别也有规则。删除一个显式无参构造器前,应看是否还有其他构造器、原有可见性、throws及父类初始化条件。原书直接说编译器会生成,需这些条件才能成立;对公共抽象类删protected构造器还可能扩大可见性,不能视为一律无行为影响。 详见删除构造器要核对可见性契约。

final参数或局部变量约束该绑定只能赋值一次,可帮助表达本段数据流;若值是对象引用,它不使对象本身不可变。使用多少属于表达与团队约定的取舍,测试也不能替代这条编译期约束。原作者删final是个人判断,不能据此把关键字说成全无作用,亦不能把它当共享对象自动线程安全。 详见局部final表达不可重新赋值。

星期字符串解析、显示归到Day,月份解析、显示和quarter归到Month,使转换规则与符号的编号约定在同一处。quarter按1到12的月份索引用1+(index-1)/3分组,依赖此范围。日期格式符号还带语言环境约定;移动方法不自动解决区域、null、显示稳定性或全部外部兼容,应让边界契约可查。 详见行为宜靠近其解释的数据概念。

示例isLeapYear要求年份可被4整除,且不能被100整除,除非也能被400整除;二月末日据此在常规天数上增加一天。它表达格里高利历的规则,不是所有历法的闰年定义。有效年份范围和历史日期解释仍由日期模型规定,不能从该公式推出库已支持任意年代。 详见闰年规则适用于约定历法。

把年月映为连续月序号,加偏移再分解成年月,可让跨年过程透明;最后以原日和目标月末的较小值作为结果日。加年也需在闰日等位置应用同类约束。该例的整数运算和工厂都有支持范围,不能直接推广到负序号、任意大偏移或溢出情况;裁剪也意味着分步加月未必等于一次合并偏移。 详见加月应先求目标再裁剪日期。

日期方法经工厂创建并返回新DayDate,没有修改接收者。若调用者只写date.addDays(7)而忽略返回值,可能误以为原日期已前进。plusDays/plusMonths的命名可提示新值组合,并应在契约与调用处接收结果;单靠名称仍不能保证所有读者理解,更不能将返回值改成调用者是否该继续的布尔。 详见返回新值的方法应显露结果用途。

getDayOfWeek表面只调用抽象日期能力,实际上还依赖序号零对应星期几;忽略这一点上移到基类,会把具体起点偷偷固定到所有实现。把起点星期做成实现提供的抽象能力,再由公共算法组合,可使逻辑依赖成为显式契约。还需限定序号与取余范围,不能仅凭无具体类名就断定实现无关。 详见上移算法前须找隐含实现假设。

DateInterval以OPEN、CLOSED_LEFT、CLOSED_RIGHT、CLOSED分别承载两端不含、含左、含右和都含的比较规则,调用方先把日期序号排序,再询问当前日期是否在内。这样不同边界语义有明确名字。要说明左/右指排序后端点,核对旧INCLUDE_FIRST/SECOND是否按同一约定;当端点相等,各规则也需分别验证,不能靠换成枚举假定兼容。 详见区间成员资格可由枚举承载。

作者发现weekInMonthToString和relativeToString在所查项目内只被测试调用,于是删除方法与相关测试。这个证据说明本地产品路径未用到,不自动排除库外调用、反射或兼容承诺。应按应用内部代码或公开库API的边界决定移除,并确认测试没有单独守护仍有价值的契约,不能为了绿灯任意删除失败断言。 详见仅测试调用不代表公开API无用。

作者报告原SerialDate有91/185语句被执行、补测后170/185,重构后的DayDate为45/53,约84.9%。类缩小后,未覆盖少量语句在百分比中的权重可能上升;跨不同代码集合只比百分比会误读验证范围。还需看未覆盖的具体行为及风险,原书说微细不值得测只是其判断,不能凭行少自动放行。 详见覆盖率变化需要看分母与内容。

原书依据 · 79 处

第17章 味道与启发

本章把前面案例的判断整理为注释、环境、函数、一般设计、Java、名称和测试七组线索。它适合作为追问“为什么这样改”的参考,不是看到一个外观就自动删改的指令:小接口、多态、短方法或枚举都需对应真实责任和变化。清单末尾也承认价值判断比穷尽规则更重要。

注释和函数条目主要回连第2至5章,构建与测试新增构建与测试应有清楚的统一入口,让维护者少依赖神秘手工步骤。一般设计先限定抽象能力,再看依赖的归属:抽象能力不应要求实现撒谎用Stack容量说明不能用假值掩盖不适用;特性依恋要结合职责取舍用计算和报表的差别说明行为迁移不能忽略展示边界;能力上限应向责任方查询把报表分页的隐含假设变成显式协作。

准确性贯穿命名与结构。解释性变量应命名中间角色、魔术值的问题是隐含意义和唯一性等假设应成为明确检查都把读者猜测变为可查契约。条件分支两侧须保持量纲一致及引用方式整理不证明工资公式注明原工资片段的可推导算术问题,未将教学例包装为真实资金事故。Java导入条目按实际名称解析解释,常量访问不应伪装类型关系则保留原三类型关系图,区分取常量与实现业务接口。

后半的命名仍以角色、抽象、作用域和副作用为依据。保龄球例说明轮次与投球位置是不同进度,名称帮助阅读但不补齐省略实现。测试条目再把忽略测试应显露未决需求、失败模式能指引进一步取样和覆盖探针帮助寻找未执行路径连接起来:待定不算通过,模式不等于根因,执行覆盖也不等于正确性证明。整章用这些边界约束启发,而不是把习惯或作者修辞变成普遍定理。

签出后四处找依赖、手工拼步骤,会让构建条件难复现。把必要获取、配置和构建组织成清楚入口,并提供容易运行相关测试的入口,可降低重复操作与遗漏。单个命令背后仍可有明确多阶段流程,不表示没有环境前提或所有测试都应塞入一次最慢运行;原书svn/ant片段只为历史示意。 详见构建与测试应有清楚的统一入口。

源文件同时包含业务语言、模板、标记与脚本时,读者需切换语法和语义上下文,也容易混淆转义和职责。可减少非必要混排,按责任隔离复杂片段,同时保留能清楚表达整体的组合。不是看到注释或嵌入字符串就必须拆文件;目标是减少理解负担,不是用语言数量机械评判设计。 详见多语言混排要看认知边界。

关闭警告、跳过失败测试或绕开检查,可能只让构建表面顺利,未消除它们提示的缺陷。必要例外应有已理解的原因、范围和处置,而不是把静默当安全。原书核事故类比未在此给充分历史论证,笔记仅保留软件检查机制的风险,不借类比证明具体事故因果或禁止所有合理配置。 详见压制告警不等于修复原因。

普通Stack若不承诺已知容量,就不宜强制提供percentFull;有界实现可在更专门的接口表达该能力。随便返回0会把“不知道或不适用”伪装成“空闲充足”,调用方可能据此作无效决策。即使容量比例已知,也不等于保证下一次分配成功;接口应描述实际可提供的能力和失败条件。 详见抽象能力不应要求实现撒谎。

高层基类若直接引用可变化的派生实现,就难以在不了解它们的情况下单独分发。把选择与实现依赖放到合适边界,有助于各组件按稳定契约演进。固定有限类型且共同部署的实现也可能合理;分成多个JAR本身不保证兼容,接口、版本和运行装配关系仍需协调。 详见依赖方向影响组件独立部署。

为方便把通用枚举、工具或常量放进某个特殊类,会迫使无关使用者知道这个宿主,制造不必要的依赖。应按概念归属和实际使用决定位置;真是宿主内部细节的类型仍可嵌套。是否拆出要有理由,不能反过来把所有嵌套类型都视为错或以文件数量判定模块化。 详见通用概念不宜绑在无关宿主。

方法不断读取另一对象的内部数据来完成该对象的业务规则,提示行为可能放错位置;薪资计算与雇员数据关系即是例子。但报表格式化即便读取雇员数据,也可独立存在,避免让雇员承担展示格式的变化。判断依据是封装和变化责任,而不是禁止任何getter调用或把所有读取都搬入实体。 详见特性依恋要结合职责取舍。

工资例overtime ? 1.5 : 1.0 * tenthRate中,true分支只返回倍率1.5,false分支却含工资率;二者不是同一单位。教学演算:若每十分之一小时工资100分、超时10个单位,true分支算15分,而按一倍半应为1500分。该问题来自所示表达式,不是已发生错付事故;拆方法仍须核对单位与预期。 详见条件分支两侧须保持量纲一致。

Math.max只根据参数计算,通常不需要接收者状态或按对象实现分派,适合静态入口。工资计算若按不同规则可替换,实例策略或相关对象行为更可能承载变化。静态与否不能只看“数据来自参数”,也不要求所有函数一律非静态;要看所需状态、替换边界和调用契约。 详见静态方法选择要看替换责任。

把正则第一组赋给key、第二组赋给value,让读者看到每个匹配结果在本段转换中的用途,不必反复从组号倒推。对复杂计算同样可用具名中间结果分阶段解释。名称仍须符合真实数据,过多无信息的临时值会增加跳转;原例没有展示正则定义,不能据key/value名证明它解析了所有合法输入。 详见解释性变量应命名中间角色。

HourlyReporter固定按55条分页,暗中假定所有HourlyReportFormatter都接受这一容量;换一个格式器时该假设可能失效。让负责格式化的协作者提供最大页容量,再按明确协议收集和输出,可使能力依赖可见。还需定义正值、边界与是否随运行变化;仅增加getter不保证任意实现都正确。 详见能力上限应向责任方查询。

数字或字符串若只有少数人知道其业务角色,会让测试与实现依赖口头约定。把7777和John Doe命名为同一测试雇员的ID与姓名,可明确它们来自何种夹具;常量名也要真实且随数据维护。不是每个2都要叫TWO,工作时长8等可变政策仍应按领域约定判断,不能以某人熟悉数值就认定无需解释。 详见魔术值的问题是隐含意义。

只取查询的第一个结果,不能证明它是唯一结果。若业务要求唯一,应以可靠约束或检查明确表达零个、一个和多个的语义,并处理意外情况。同理,可能为空的结果与并发更新都需要相应契约,不能把最常见路径当全部保证;检查的并发时机也须与实际状态变化范围一致。 详见唯一性等假设应成为明确检查。

使用整数或以整数承载的Money,可避免把货币值随意当二进制近似小数处理,但整数本身没有币种、单位和舍入含义。应说明每个整数代表何种单位,涉及比例计算或分配时按业务规则处理余数,并考虑范围。原文只要求精确表示和恰当舍入,不能从“用了int”推断所有金额计算已正确。 详见整数金额仍需单位与舍入约定。

只靠约定要求每个switch处理所有变体,可能在某处遗漏;抽象方法可让具体类必须给出实现,使部分义务由编译结构承担。但空实现、抛异常占位或错误算法仍可能编译,结构约束不等于完整业务正确。应选择能表达真实变化的结构,并与契约测试配合,而不是为所有条件都创建继承层。 详见结构约束可强化实现义务。

import package.*把可访问类型纳入简单名解析范围,不会把包内全部类型装入程序,也不会让实际使用的类不再是编译依赖。指定导入与通配导入影响可读性、名称解析和冲突处理,应按团队约定选择。原文把通配导入说成减少真正依赖,只适用于未使用的导入声明差别,不能推导模块已解耦。 详见通配导入不会消除实际类型依赖。

Employee为取得PayrollConstants中的常量而implements接口,会把常量来源隐藏进继承路径,也让本无该业务角色的类型对外多了一种类型关系。静态导入或显式限定可让取用常量与实现契约分开。选哪种写法仍要让来源易查,改变导入不会修复工资算法;公开类型关系的移除还须检查外部兼容。 详见常量访问不应伪装类型关系。

常量继承改静态导入,以及工资档位改枚举后,例中仍用全体工时作基础,再加1.5倍超时工时。若政策是超时合计一倍半,全体工时已含一倍基础,这会算出超时二点五倍;应按明确政策检查总额与附加额含义。hourlyRate与十分之一小时工时的单位也未交代,不能仅因结构更清楚就视为可靠薪资实现。 详见引用方式整理不证明工资公式。

保龄球例用十轮循环控制计分次数,用另一个索引指向投球记录:全中计十加后两球并前进一球,补中计十加后一球并前进两球,普通轮计两球和并前进两球。具名函数让两种进度易于辨认。示例未列所有helper与合法输入校验,不能由名称推断末轮奖励球、越界等已完整实现。 详见计分过程要区分轮次与投球位置。

需求不明确时,待定测试可保存对行为的疑问,帮助后来讨论具体输入和期望。@Ignore或注释使其不参加正常判定,意味着该行为仍未验证,不是通过;应记录未决原因和恢复条件。它与偷偷屏蔽已确认契约的失败测试不同,不能靠缩小执行集合宣称功能完成。 详见忽略测试应显露未决需求。

把输入条件与通过/失败对应起来,可能发现长于某长度或某参数为负时集中失败,从而缩小边界或计算问题的调查范围。发现一个缺陷后,再检查附近条件和相关分支,避免只修单个用例。模式是定位线索,不能仅凭相关性断定根因,也不保证缺陷总会扎堆。 详见失败模式能指引进一步取样。

覆盖工具把实际测试执行到的行与分支显露出来,未触及的if或catch可提示还缺哪些场景;结合失败用例和条件分析,有时能发现永不进入的错误分支。颜色或百分比只代表工具记录的执行范围,不能证明断言正确或条件组合完备。应解释缺口对应的业务,而不是只把红色行变绿。 详见覆盖探针帮助寻找未执行路径。

原书依据 · 26 处

附录A 并发编程II

本附录将第13章的概览展开到请求服务、字节码模型、并发库、复合API、资源等待和测试。先以串行服务与请求调度说明I/O等待可与独立工作重叠,再把线程选择从请求处理分开;随后追踪自增为何丢更新,并区分线程私有栈、共享对象与原子操作。全部中间代码、图片和A10示例均已读,原书缺失或重复代码没有被当作可执行完整项目。

性能时限应同时验证工作完成限制“十秒内结束”的结论,调度策略可从请求处理分离提供结构接缝,固定工作线程不限制积压任务则补足资源容量判断。交错数量依赖简化执行模型只计约定的线性排程,不是JVM全部行为或故障概率;原子读写不等于复合动作原子与私有操作数栈仍可带共享引用把表示、可见性和复合更新分清。Future负责结果汇合,CAS负责原子条件更新,二者都不能替代更大的业务契约。

共享容器与迭代器进一步说明多个同步方法不等于整段原子。原子条件插入须保护整个判断和取值与结束判断可合成原子入口把有条件动作收拢到协议边界;Local705经历是输出缓冲的状态不一致与终端停滞,未据此推断错账。吞吐图是平均I/O与解析的理想稳态模型,原PageIterator锁内慢调用与缺return不能被当作模型已实现。

死锁部分从两个反向获取的有限池出发,逐项解释四条件,再比较可共享资源、释放重试、协商回收与统一顺序的代价。统一资源顺序可消除等待环针对的是完整覆盖的资源协议,不能保证饥饿和性能问题全消失。测试部分又区分找反例测试的绿灯有特殊含义与普通回归绿灯,用ConTest的历史介绍说明扰动作用而不声称当前可用或本轮复现。最后的Server关闭和MessageUtils收发只展示部分生命周期与协议,异常资源清理、队列结束和缺失客户端测试仍有明确限制。

10秒内所有客户端线程结束,只约束测试观察到的耗时;若客户端catch后只打印错误,快速失败也可能很快结束。吞吐验收还需确认请求数量、回应内容与失败计数,再记录环境和负载。原例省略了设置,后附ClientTest实际重复Server,不能据测试名或作者一秒多叙述宣称本轮已证明端到端成功。 详见性能时限应同时验证工作完成。

服务器接收连接后构造ClientRequestProcessor,再交给ClientScheduler;逐请求线程和Executor调度实现同一schedule能力。这样可替换任务如何获得执行机会,而让请求逻辑集中在process。隔离线程创建不表示共享数据问题只会出在调度器,连接生命周期、请求副作用和关闭协议仍需各自负责。 详见调度策略可从请求处理分离。

newFixedThreadPool约束同时工作的线程数量,却使用共享无界任务队列;请求持续超过处理能力时仍可能积压并耗内存。每请求新线程与固定池是不同容量策略,都需明确排队、拒绝、等待和结束责任。所示字段仅声明Executor且无关闭入口,不应当作已实现有界服务或完整线程池生命周期。 详见固定工作线程不限制积压任务。

假设T个线程各有N步、每线程内部顺序不变、所有步骤都可任意交错,则线性排程数为(TN)!/(N!)^T。两线程各两步可排六种;八步模型给12870。这个数不是实际JVM全部合法执行,也不是出错概率;编译、锁和内存模型会改变可发生的行为。整段互斥时只比较线程完成顺序,T线程为T!,原文N!符号混用应区分。 详见交错数量依赖简化执行模型。

int字段单次赋值的原子性不使读、加、写组成的++原子,也不独自提供跨线程可见性。JLS允许非volatile long/double按两部分处理,但不是所有JVM都必须拆写;volatile对应读写有更强约定,++仍需复合原子机制。原文把64位写一律说成两次的表述应限定,不能据字节数直接推断同步正确性。 详见原子读写不等于复合动作原子。

调用帧保存本次方法的局部变量与操作数栈,this指向接收对象;每个线程有自己的临时读值,不等于接收对象也独占。GETFIELD读到42后暂停,另一线程写43,原线程栈里仍可保留42再写43,导致丢更新。要同时看线程私有中间状态和共享字段,不能从“局部”推导没有竞争。 详见私有操作数栈仍可带共享引用。

向ExecutorService提交Callable后先做独立本地工作,最后通过Future.get取得异步结果,可让两部分重叠。get在结果未就绪时阻塞,还需处理失败、取消、中断和超时等契约;只有确实独立的工作才能如此安排。Executor、ExecutorService、Runnable和Callable角色不同,原文Callback是误称,不能把所有接口说成同样接收并返回结果。 详见Future结果等待放到汇合处。

CAS仅在共享值仍等于预期值时安装新值,否则失败并允许调用方重试;检查和写入必须是同一原子动作。原文模拟返回旧值,现代compareAndSet返回成功与否,两种结果约定不可混用。依赖旧值的计算需在失败后按新状态重新求值,重试代码也要控制副作用;无锁不保证每个线程无等待或性能总胜锁。 详见比较交换把条件与更新合为原子。

containsKey和put各自线程安全,仍可在两调用间被另一线程插入,导致覆盖原想保留的值。需要同一有效互斥范围包住整段,或使用契约明确的putIfAbsent。原WrappedHashtable片段写成if(map.containsKey(key))才put,逻辑反了,不能当正确实现;锁也不能只保护新包装而让其他路径绕过。 详见原子条件插入须保护整个判断。

共享迭代器的hasNext与next分别同步,末项仍可被两线程先后认作存在。服务端把“若有下一项就取出,否则结束”放进一次getNextOrNull调用,可让检查与推进共享同一锁;适配层也需独占内部迭代器。null在这个API明确表示结束,若合法元素也可为null就需其他结果类型;线程安全不保证取出后的工作只成功一次。 详见取值与结束判断可合成原子入口。

会计软件的终端输出缓冲区在一处使用时漏锁,使指针显示空、计数却显示满:既无数据可显示又不能加入新数据,终端停滞。重启或定期重置能暂时恢复显示,却没有证明漏锁根因已消除。该经历说明多处客户端各自守约会扩大遗漏面,不证明发生账目或金额错误;强制重置还需考虑丢弃未完成状态的语义。 详见漏锁可破坏缓冲区状态不变量。

线程可在短临界区独占取得下一个URL,再在各自上下文执行网络读取和解析。若把getPageFor也放在同步getNextPageOrNull内部,所有共享该实例的读取仍会串行,难以形成图中I/O重叠。原片段还缺少返回结果并与“各线程独有PageReader”描述不一致,故只能据设计目的讨论分离,不能直接据代码宣称三倍提速。 详见慢读取不宜占住任务分配锁。

假设每页I/O一秒且不占CPU,解析半秒占满单CPU,串行每页需一点五秒;若三工作者的I/O独立重叠且解析恰好接续,稳态CPU每秒解析两页,可达串行吞吐的三倍。启动、尾部、锁、连接和带宽限制会改变短批耗时,这不是实测,也不是任意三线程算法的加速比。 详见理想流水吞吐要声明资源假设。

两组操作分别先持有数据库连接、先持有MQ连接,若两个池都被占满,各线程再等另一池就会互相卡住。触发依赖持有不释放和资源有限,不是用户数多就必然死锁。原文前面创建/更新顺序与后续十线程叙述对调,笔记保留对称的反向获取机制,不把操作标签当可靠顺序规范。 详见反向获取有限资源池可能死锁。

互斥使资源不能同时任意使用,持有并等待让线程拿着已有资源再求其他资源,不可抢占使占用不能被外部直接收回,循环等待则连成相互依赖环。经典资源模型中四条件同时成立才可能死锁;破坏其中之一可消除相应死锁条件。它们不是所有挂起或性能问题的定义,需按实际资源与等待关系分析。 详见死锁分析要同时检查四个条件。

可将某些共享更新改成原子操作,或设计可并行使用的资源,从而减少独占持有;增加足够容量有时也能避免特定资源等待。不能把数据库连接等有状态资源简单当AtomicInteger替换,容量扩张也非普遍解法。先查看资源是否真的可同时使用;单独“检查可用”后再获取仍可能竞争,检查不是预留。 详见移除互斥要匹配资源本质。

需要多项资源时,若后续获取失败就释放已有占用并重来,可破坏持有并等待。它要求失败、退出和异常路径都按协议释放,不能只先查一下可用性。多个线程同节奏退让可能活锁,某线程也可能长期饥饿;重试的节奏、界限与观测要结合负载设计,不把“不死锁”当有用进展保证。 详见失败释放重试仍有活性代价。

繁忙时请求持有者释放资源,可在协议允许的安全点撤销占用,再重试完成工作;管理这些请求和状态需要额外协调。持有者必须能合法响应,不能让另一线程任意释放Java监视器或丢弃不可回滚工作。原文把它列作抢占策略,实际示意是协作释放,不保证所有资源都可安全抢占。 详见协商释放不能当强制夺锁。

所有参与者按同一严格资源次序获取资源,就不会一部分持较后资源去等较前资源而形成循环。协议须覆盖同一问题里的全部路径;只让某两段代码一致不保护遗漏入口。代价可能是较早持有暂时不用的资源,动态发现后续资源时也要重新考虑协议,不能宣称排序解决所有等待与吞吐问题。 详见统一资源顺序可消除等待环。

twoThreadsShouldFailEventually在观察到计数未加二时直接return,因此测试通过代表找到了产品缺陷;循环内一直未见异常反而调用fail,表示没暴露出已知问题。它和常规回归测试的绿灯含义不同,报告必须说清判据。原例nextId与lastId不一致,循环样本也不能推出可靠故障概率或所有平台必现。 详见找反例测试的绿灯有特殊含义。

ConTest是本书介绍的历史并发测试工具,可装置测试与生产类,改变运行时机,使原本少见的竞争更容易进入测试观察范围。使用流程是先有多用户多负载测试,再装置并运行;结果仍依赖判据和环境。书列十余次发现位置只说明该实验,不能保证固定几十次就找到所有错误,也未证明该工具当期可用。 详见ConTest扰动暴露竞争。

Server用volatile keepProcessing表达退出请求,并在stopProcessing关闭ServerSocket,使accept中的阻塞可因异常结束后观察循环条件。只有写标志而不处理阻塞等待,退出可能拖延。关闭监听不等于已接受连接或工作线程都完成,process失败路径也未确保释放socket;该例展示一部分关闭机制,尚非完整平静关闭协议。 详见停止标志不自动唤醒阻塞接收。

MessageUtils发送时先建ObjectOutputStream,再writeUTF并flush;接收建立ObjectInputStream后readUTF。双方需要匹配这种流包装,而不是把它当无额外帧信息的裸UTF文本协议。示例按每次调用新建包装,复用长连接、多消息、错误中断和资源所有权还需另定;一次正常收发不证明这些情况已解决。 详见消息内容与流帧格式需匹配。

原书依据 · 33 处

附录B org.jfree.date.SerialDate

本附录保存第16章所讨论的原始代码、测试与重构后实现。附录B已按原顺序完整读完B-1至B-16:原始日期类、两套测试、月份常量、具体日期实现及年度相对日期规则,继而是DayDate和各枚举、工具、工厂与具体实现的最终清单。书中用省略号省去的许可行按省略处理,不补造源码;全部测试只作为文本证据,未在本机编译或执行。原始代码既为前文算法和职责判断补足来源,也显露新增的契约边界,不能以正文讨论过就跳过本附录。

日期值与时间点有不同契约先说明这个类为何存在,随后对照其共享格式符号与可变description,分别限定final和不可变的承诺。月份转换中回退解析应重置失败状态显示无效数值如何流到最终结果,闰年累计必须说明包含端点则说明日期序号累计的计数前提。月末裁剪、严格前后星期、最近星期、错误字符串和工厂具体实现等已在第16章解释,现补充完整原源码位置。

原B-1唯一构造器是protected SerialDate(),而类是public abstract;这一事实使删除构造器要核对可见性契约有了具体适用情形:删去唯一声明后隐式默认构造器将取类的public级别,不是原声明原样复现。原区间文档强调参数次序无关,具体如何处理两端含义仍要等待读实现来确认;抽象签名不当作算法已经核验。

只想表达某一天时,时分秒和时区可能不是领域值的一部分;java.util.Date表示时间点,把同一时刻投影为哪天还受时区影响。SerialDate的设计动机是单独表达日期,而非更精确的时间。二者转换需要补充时区与日内时间约定,不能认为丢掉时分秒就是无损互换,也不把历史自定义类当当前唯一实现。 详见日期值与时间点有不同契约。

SerialDate公开static final DATE_FORMAT_SYMBOLS,final只阻止引用被重新赋值,DateFormatSymbols本身仍有修改符号的方法。若外部改变这份对象,之后日期名称解析和显示会共用被改的内容。需要区分变量固定与配置不可变,明确谁能改、何时生效;原例没有保证默认语言环境变化会自动刷新已有静态实例。 详见final引用不会冻结格式符号。

stringToMonthCode先尝试把输入解析为整数;不在1到12时再搜索名称,却没有在搜索前恢复失败标记。输入13时数值解析成功、名称查找失败,最终仍可返回13,违反文档“不能识别返回-1”的契约。原第16章修正片段先置result=-1;这说明多阶段解析不能让早期无效中间值冒充最终成功。 详见回退解析应重置失败状态。

leapYearCount按从1900起至给定年份(包含该年)计数,四年倍数先加,再减百年倍数、加回四百年倍数。示例公式以1896、1800、1600为偏移基准:1900得到0,1904得到1,2000得到25。它用于支持范围内的日期累计,不是任意负年或其他历法的公式;用在年初/年末前应核对是否要排除当前年。 详见闰年累计必须说明包含端点。

SerialDate的注释写日期类不可变,但它又公开setDescription修改描述。年月日值不变和对象所有可观察状态不变是不同承诺;使用者若共享整个对象,不能仅由类注释假定没有变化。应明确元数据是否属于不可变值或另行存放,而不是以字段看似无关为由忽略公共修改入口。 详见不可变承诺要说明状态范围。

只检查前一个星期一的dayOfMonth为5,不能独自排除结果是另一月或另一年的5日。若契约要求具体日期,宜比较完整年月日或语义完整的日期值,并保留跨月、跨年边界。测试选择局部字段可以服务特定子问题,但不能由局部断言通过扩大为完整日期正确;相等比较本身也要有明确语义。 详见日期断言要覆盖所需完整结果。

原测试断言Saturday、Wednesday和January,实际转换却取默认Locale的名称,注释也承认非英语环境会失败。应让测试的语言前提明确并控制相关配置,或按指定环境建立正确期望;简单换机器语言不是修复算法。若修改全局默认Locale,还须考虑恢复与并行隔离,已初始化的静态符号也不必自动重建。 详见本地化测试需要声明语言环境。

把一个日期序列化到内存,再用同一套类定义读回并比较,能约束当前对象的往返值保持;它没有用旧版本生成的数据,不能证明新旧版本互读。类名、UID和字段迁移仍需另有兼容策略与证据。原例catch只打印异常,最后d2为null的比较可失败,但会把具体原因留在输出中,诊断不如直接保留异常清楚。 详见序列化回环不证明跨版本兼容。

MonthConstants用一月1到十二月12,而java.util.Calendar用一月0到十二月11;同一含义的符号不代表底层整数可直接互传。跨边界要明确编号映射,避免差一月。枚举可帮助区分域,转换处仍需按目标契约处理,不能用全局加一或减一替代对每个API语义的确认。 详见相同月份名不保证编号相同。

对每个月验证parse(format(m))等于m,可发现两函数在某些值上的不一致,但两边若共享同一个错误映射,也可能一起往返成功。需另有已知月份名称、编号和非法输入的独立期望,区分内部一致与外部正确。原测试同时有固定名称例及被注释的0/13例,后者并未参与执行,不可计作已验证边界。 详见往返测试不能替代外部语义判据。

原测试与新增测试让前述契约有了可定位的例子。日期断言要覆盖所需完整结果区分只看日号和比较完整日期,本地化测试需要声明语言环境解释英文名称断言为何依赖默认配置;序列化回环不证明跨版本兼容限制一次内存回读能证明的范围。MonthConstants则明确一基月份与Calendar零基月份的差别。

作者新增的测试同时保留注释掉的大小写、0/13、同日following和未来nearest等断言。它们为第16章讨论的改动提供背景,仍不是已执行结果;其中需求偏好与实际边界错误需要分别判断。往返测试不能替代外部语义判据说明parse/format内部一致仍需独立名称和非法值的预期。全部七种星期、月末与跨年断言及后续具体实现均已读;测试源码的存在仍不能代替执行和判据有效性的证据。

SpreadsheetDate同时保存序号和年月日。由年月日构造时先验证再计算序号,由序号构造时则反算年月日;二者描述同一天才构成有效对象。冗余字段便于查询,也增加同步责任。新增修改入口、反序列化或改变换算规则时,应关注整个表示是否一致,不能只验证被直接赋值的字段;本例正常构造后没有日期修改器,不据此声称已发生失步。 详见冗余表示需要同步不变量。

RelativeDayOfWeekRule先用super.clone复制自身,再单独克隆subrule,避免副本直接复用同一个可变规则引用。但“深克隆”是否成立仍取决于子规则的clone怎样处理其下层对象;一层显式克隆不证明整个对象图全部独立。应按实际需要独立的状态界定边界,并考虑空引用、循环引用和共享资源;本段没有展示所有子规则实现,不补造它们的行为。 详见克隆边界取决于对象图。

RelativeDayOfWeekRule.getDate的职责是按规则计算某年日期。代码用null承载子规则没有日期的情形,但relative落入default时也返回null;调用者无法单凭结果辨认合理缺席与无效选择。可以在构造或设置规则时拒绝非法值,或用明确结果表达原因。subrule本身为null还会在调用时失败,不能把这类错误也算成正常无日期;本例允许null结果不等于所有无效输入都合理。 详见无日期不应掩盖无效规则。

具体日期实现把抽象契约落实为序号与年月日。冗余表示需要同步不变量解释为何两种构造器必须双向换算;原始和最终版本都保留1900年1月1日对应序号2的基准,星期计算也随该基准确定。原始SpreadsheetDate的区间实现先min/max排序,再解释INCLUDE_FIRST与INCLUDE_SECOND,所以它们实际对应较小端和较大端;最终DateInterval用LEFT与RIGHT让同一约定更直接,不能仅由参数名猜成传入次序。

RelativeDayOfWeekRule把一个年度子规则的结果作为基日,再选前一个、最近或后一个指定星期。无日期不应掩盖无效规则说明结果缺席与配置无效需要分别表达,克隆边界取决于对象图则限定clone对共享状态的处理范围。它们是原书附录提供的具体协作例,不是已完成现代库兼容改造。

最终版本把日期运算留在DayDate,把月名、季度、普通月末放在Month,把星期编码放在Day,把开闭关系放在DateInterval;DateUtil连接闰年与月份,DayDateFactory连接创建策略和实现能力。这个重组让职责更容易定位,仍保留默认语言环境、全局工厂、null边界和序号假设。阅读应同时观察结构改善与行为契约,不能因为清单标为“最终版本”就省去验证。

原书依据 · 27 处

结束语

作者用一条写着“沉迷测试”的腕带结束全书:它在日常编码时提醒自己遵守职业承诺。这里没有新增编码规则,而是把前面关于命名、函数、测试和重构的讨论重新落到持续行动上。腕带是作者的个人经验,不能由此推导提醒物必然改善所有团队的质量。

结束语承接序言的职业态度,也回应三个重构案例:整洁代码需要在具体修改中持续投入,不能只停留在认同规则。测试为修改提供反馈,但一份测试清单或一次通过仍有覆盖与判据的边界;这是正文案例已经说明的实践要求,不能把作者的承诺当作质量保证。

跨章综合

名称与契约需要一起判断。名称把对象和动作暴露给读者,契约则说明输入、结果、状态变化和失败的含义。查询与动作应有清楚的结果语义连接函数设计与Args案例:能识别参数类型、成功设置值、是否继续循环是不同事实,返回值应描述方法实际负责的结果。拆分函数也应保留这些事实,而不是只让调用方分支变短。

测试和重构互相支撑,又各有边界。测试为修改提供行为约束解释为什么修改应有可重复判据;改变索引约定要同步边界使用则说明一个内部表示变化也会影响所有读它的位置。日期附录里的往返测试不能替代外部语义判据进一步提醒,测试通过可能只说明两段实现内部一致,仍需独立期望、边界输入和环境前提。书中的覆盖率数字是作者当时的观察,不是本次实测。

“把责任放在合适地方”贯穿对象、边界、系统与日期案例。行为宜靠近其解释的数据概念将月名和季度放回Month,让调用方减少对内部规则的重复理解;创建工厂则把具体实现的选择集中起来。但静态可替换工厂仍有全局状态说明结构更清楚之后仍要检查共享作用域,替换一个全局入口不等于每个客户都能独立配置。并发章节进一步把这种共享状态问题转成原子性、可见性和资源等待的明确约束。

全书的启发应作为提出问题的工具。函数过长、名称含糊、注释过多或重复计算都可以提示继续调查,却不独立证明缺陷。先说明当前责任、保留外部行为、做小步变换,再核对结果;每次修改留下局部改善把这种做法落在有限范围,而不是要求一次重写全系统。

原书依据 · 20 处

发散与实践

以下为读者延伸。两份计划已交付,首轮公开源码映射已准备;完整阅读练习、代码变更与行为实验尚未执行。

  1. 沿比较消息追踪差异边界:以JUnit 4.13.2的固定版本为对象,用90分钟追踪断言失败、共同前后缀和空差异片段,并对照真实测试。
  2. 把局部改善限定在一次修改:针对本地笔记生成辅助脚本安排7天记录,比较改名前理解成本与改后职责表达,避免扩成未经安排的全面重构。
生成进度与管理记录

代码整洁之道

Skill 版本:v24

执行模式:light

建档进度:done

信息浓度:高

稳定性:高(知识主体较耐久)

四象限:经典原理

评级依据:沿用总表高浓度/高稳定性(经典原理)。评级实读样本:内容提要、序/译序/前言、第1章全部正文,以及第14章首单元Args的接口/解析映射代码、第17章首单元注释/构建/参数启发。它们不仅罗列语法,还解释重复、表达、维护成本和逐步改进的理由;命名、职责与边界等主体可迁移。具体Java/JUnit/JCommon/并发库和命令仍带版本条件,作者门派式建议与启发不作为数学定律或全部项目最佳方案。评级抽样不代表后续案例或附录已读,全部正文仍逐单元处理。

整书笔记(全文讲解与定位已完成);覆盖记录。本次按book-notes –mode light,未执行生成后复核、独立审查及审查优化。

章节进度追踪表

章节号 章节标题 状态(pending/done) 卡片数
005 内容提要 done 0
006 序 done 7
007 关于封面 done 0
008 代码猴子与童子军军规 done 0
009 前言 done 1
010 第1章 整洁代码 done 18
011 第2章 有意义的命名 done 23
012 第3章 函数 done 27
013 第4章 注释 done 24
014 第5章 格式 done 16
015 第6章 对象和数据结构 done 12
016 第7章 错误处理 done 13
017 第8章 边界 done 9
018 第9章 单元测试 done 16
019 第10章 类 done 13
020 第11章 系统 done 16
021 第12章 迭进 done 7
022 第13章 并发编程 done 21
023 第14章 逐步改进 done 25
024 第15章 JUnit内幕 done 8
025 第16章 重构SerialDate done 17
026 第17章 味道与启发 done 22
027 附录A 并发编程II done 23
028 附录B org.jfree.date.SerialDate done 13
029 结束语 done 0

非正文排除

spine项 类型 排除理由
001 封面 仅图片封面,无独立正文
002 目录 导航目录;具体正文按spine顺序列入,不以目录代替阅读
003 扉页 书名作者译者出版社身份页,信息写元数据,不作为技术正文
004 版权 CIP/版权与出版发行信息,已全文核对用于出版元数据

待关联术语

术语名 出现章节 一句话语境
CAS、Future、ExecutorService、Callable、操作数栈、四个死锁条件 027 附录机制展开,字节码交错公式为简化模型,示例未执行
Feature Envy、最小惊异原则、DRY、Strategy、Codd Normal Forms、共同语言 026 前三者有实质讨论并入/成卡;Strategy/范式仅提名不补造全集
DayDate、SpreadsheetDate、DayDateFactory、DateInterval、解释临时变量 025 日期抽象/实现能力/边界语义,附录全文已完成读取
ComparisonCompactor、共同前缀/后缀、contextLength 024 单区间差异消息及有限上下文,非通用最小编辑diff
Args、范式字符串、ArgumentMarshaler、ArgsException 023 本书自写参数解析协议与渐进重构例,不作通用CLI库使用指南
临界区、互斥、饥饿、死锁、活锁、ReentrantLock、Semaphore、CountDownLatch、Executor 022 表13-1/2及执行模型;线程所有权、许可和一次性条件有不同契约
简单设计、单一事实来源、Template Method 021 按优先顺序迭进,共同算法/差异钩子不补造地区业务规则
DI、IoC、JNDI、POJO、横切关注面、AOP、BDUF、DSL 020 组装、运行及策略边界;创建时机/不手改源码/提前设计均需区分
SRP、内聚、OCP、DIP、StockExchange 019 类责任、变化隔离与询价抽象;原则按实际变化轴而非方法数量判断
BUILD-OPERATE-CHECK、given-when-then、测试DSL、FIRST、Template Method 018 场景表达与测试质量;模板法仅提名,不补造模式实现
learning tests、Adapter、seam、FakeTransmitter 017 API理解的试验与受控替换接缝;假实现验证和真实适配验证需区分
checked exception、unchecked exception、Special Case 016 编译期处理义务与正常业务特例;非受检不等于不可捕获,特例不是吞没失败
DTO、Active Record、Visitor、双向分派 015 传输与持久化角色及扩展轴例外;Active Record按本书建议与Fowler定义区分
对数标尺、标准差σ、直方图、中位数 014 图与CodeAnalyzer实际计量所涉;样本数据和σ解释不完整,不补造实验结论
Javadoc、TODO、伪唤醒、筛法、Base64 013 对应注释职责、待办与样例中实质机制;不会把完整代码样板当已验证工具
单一职责SRP、开闭OCP、DRY、指令询问分隔、结构化编程 012 已按实际解释保留变化理由/扩展边界/共同步骤/接口责任/退出取舍,历史理论全貌不补造
匈牙利语标记法、抽象工厂、Visitor、JobQueue 011 名称编码与术语来源的情境例;模式未在本章完整展开,不增造机制卡
单一权责原则SRP、开放闭合原则OCP、依赖倒置原则DIP 010 仅预告后续引用,未在本章独立解释,留待正文展开
领域特定语言DSL、破窗比喻、LeBlanc警语、字面编程 010 精确表达及持续照料的背景线索,不把格言当实证规律
TPM、精益、Scrum、TDD、耦合与内聚 006 序言维护与设计论证中提名,具体机制留待后文

引用文献

标题 类型(书/论文/框架/源码项目) 出现章节 一句话语境
SpreadsheetDate、RelativeDayOfWeekRule与DayDate最终实现 源码项目 028 B-5/B-6与B-7至B-16完整读取;原书省略许可段不补造;未执行代码
SerialDateTests.java、MonthConstants.java、BobsSerialDateTest.java 源码项目 028 B-2/B-3/B-4完整读;测试仅为源码证据,未在本机执行
org.jfree.date.SerialDate.java 源码项目 028 B-1本地历史文件,版本注释2005-11-03 v1.7,完整1034原行已读
ConTest 源码项目 027 A8介绍装置与运行流程,实质内容生成延伸参考卡,当前可用性未核
Implementation Patterns 书 026 Kent Beck,本书参考表列2008,解释变量引文
Domain Driven Design 书 026 Eric Evans,2003,共同语言引文
Hardcore Java 书 025 Robert Simmons Jr.,2004,final风格主张的对照引文
Smalltalk Best Practice Patterns 书 025 Kent Beck,1997,解释临时变量参考
JCommon / org.jfree.date.SerialDate 源码项目 025 本书历史重构对象,本文片段与完整附录分开阅读
JUnit Pocket Guide 书 024 Kent Beck,O’Reilly,2004,p43起源叙事引用
JUnit、FitNesse 框架/源码项目 023 作者单元/验收回归的叙事,未在本轮执行测试
Concurrent Programming in Java: Design Principles and Patterns 书 022 Doug Lea,第二版1999,库与模型参考
The Pragmatic Programmer 书 022 Hunt/Thomas,本书列2000,DRY引用
IBM ConTest 源码项目 022 原书调度扰动工具提名,未核当前可用性/未运行
Extreme Programming Explained: Embrace Change 书 021 Kent Beck,1999,简单设计四规则引用
Inversion of Control Containers and the Dependency Injection pattern 文章 020 Martin Fowler,依赖注入引用线索
XUnit Patterns 书 020 原书列Gerard Mezzaros,2007,测试替身参考
A Timeless Way of Building 书 020 Christopher Alexander,1979,城市/领域语言背景
Eclipse AspectJ 书 020 Colyer等,2005,方面工具参考
Software physics and computer performance measurements 论文 020 Kolence,1972,软件物理仅引文
ASM、CGLIB、Javassist、AspectJ、JBoss AOP、Spring、JMock 框架/源码项目 020 代理/方面/DSL工具提名,历史配置不作当前使用指引
Object Design: Roles, Responsibilities, and Collaborations 书 019 Rebecca Wirfs-Brock等,2002,权责定义参考
Literate Programming 书 019 Donald E. Knuth,1992,PrintPrimes为本书所用改编Java例
RSpec: Behavior Driven Development for Ruby Programmers 书 018 本书所列Hellesøy/Chelimsky,2008,given-when-then语境
Professionalism and Test-Driven Development 论文 018 Robert C. Martin,IEEE Software,2007,三定律引文
Test Driven Development 书 017 Kent Beck,2003,学习性测试引文
Design Patterns: Elements of Reusable Object Oriented Software 书 017 Gamma等,本书标1996,Adapter引用线索
Working Effectively with Legacy Code 书 017 2004,seam接缝引文
Apache log4j 框架 017 历史日志配置探索,不作当前版本用法指引
Agile Software Development: Principles, Patterns, and Practices 书 016 Robert C. Martin,2002,受检异常讨论的参考来源
Refactoring: Improving the Design of Existing Code 书 015 1999年Martin Fowler等著,脚注联系特性依恋,本章未展开重构全集
Law of Demeter 设计原则/研究项目 015 近邻协作与结构依赖,核对原项目对象形式限定简写
JUnit4.3.1、TestNG、Time and Money、JDepend、Ant、Tomcat、FitNesse 框架/源码项目 014 历史样本分布与布局例,不作为当期版本尺寸或质量比较
RFC2045第6.8节 规范 013 Base64完整组编码机制被原书引用,本轮仅解释实际摘录,不声称读完RFC全文
JavaSE21 Object.wait、Comparable、SimpleDateFormat 规范/源码项目 013 生成时核对等待条件/比较符号/格式器共享边界
Tomcat、Apache Commons、JUnit4、The Elements of Programming Style 框架/源码项目/书 013 注释样例与警示的来源,未宣称本机安装或执行
The Elements of Programming Style、Design Patterns、Structured Programming 书 012 向下阅读、工厂和结构化控制背景,未声称阅读全文
JUnit、FitNesse 框架/源码项目 012 单元测试与Web测试页示例,FitNesse代码标20070619历史版本
Java语言规范SE21第13章、JUnit4.13.2 Assert 规范/源码项目 012 生成时核对枚举/throws二进制兼容与浮点delta含义,非运行验证
JavaBeans规范 框架/规范 011 get/set/is属性约定的原书来源提名,未假定所有语言和接口必须遵守
The Pragmatic Programmer、Object Oriented Analysis and Design with Applications、Working Effectively with Legacy Code 书 010 破窗比喻、可读结构、代码照料的被引背景,未声称读完原书
Extreme Programming Installed、Extreme Programming Adventures in C#、The C++ Programming Language 书 010 整洁代码定义与实践者背景引用,具体保留本章实际观点
The Elements of C# Style(C#编程风格)、Object Mentor 书/源码项目 008 译者经历与作者流派背景,未展开接口或独立机制
Implementation Patterns(实现模式)、Literate Programming(字面编程)、Agile Software Development: Principles, Patterns, and Practices 书 006、010 已读前置与第1章的设计/表达背景,未声称阅读被引原书
Christopher Alexander模式语言、Abstraction Descant 书/论文 006 持续局部修复及抽象讨论的引用,未展开完整体系

资金安全问题案例

问题标题 问题卡 解决方案卡(如有) 出现章节 一句话说明

实践卡进度

序号 实践标题 实践方式 状态(pending/done) 关联章节 产出
001 沿比较消息追踪差异边界 实现深读 done 15 ideas/idea-001-沿比较消息追踪差异边界.md;已核验固定标签/提交、4文件、首轮映射与两层计划
002 把局部改善限定在一次修改 行为实验 done 1、15 ideas/idea-002-把局部改善限定在一次修改.md;7日基线/干预计划,尚未执行

实践候选筛选:done

采用:JUnit固定实现深读;本地辅助脚本局部改善行为实验。合并:空差异/前后缀/上下文裁剪并入同一源码计划。暂不采用:重写Args或日期库,已有成熟源码可读且不需要重复实现;并发故障实验不作为当前最小实践。两卡为计划交付,完整实践未执行。

全书收束:25项实质正文、172单元已读并生成;331知识卡、2实践计划。全书主线/跨章综合与实践入口已写整书笔记。轻量模式:未执行复核、审查及审查结果优化。

相关主题

从本书的主题进入跨书阅读,对照其他书籍的讲解。下方数量包含主题关联的全部卡片与书籍。

暂无公开主题。