《活文档》推荐序(文末有惊喜)
我们是否听够了这样的抱怨？
我要维护的遗留系统乱得一团糟，像迷宫一样找不到出路。文档都是错的。开发这个系统的人早溜了，根本没法维护！
写的什么代码！简直恶臭难闻，当初写代码的人到底是干什么吃的？
压根儿就没有自动化测试，每改一处代码都要小心翼翼，就怕不小心踩到雷啊！
架构师是专门做PPT的吗？画了这么多漂亮的设计图，对开发实现却没什么参考价值！
敏捷不是不提倡写文档吗？怎么还让我天天写文档写到吐！关键是写了文档也没人看，简直是浪费！
或许深谙开发工作的老鸟会风轻云淡地说：“淡定，淡定！哪个系统不是这样开发的呢？只要需求总在变化，这些问题就是不得不存在的技术债，慢慢还吧！”说罢，继续为了追求进度疯狂写代码，制造更多总也偿还不完的技术债。直到有一天，当他接手这样一个满目疮痍的软件系统时，也开始了比以上抱怨还要激烈的哀嚎！
如果说开发新系统是一项高难度的工作，那么维护旧系统要比这难上一百倍！如果说编写新代码是一件痛苦的事儿，那么写文档要比这痛苦一百倍！俗语说：“虱子多了不咬，债多了不愁！”哪个开发人员不是扛着一堆债务还要冲锋陷阵呢？然而当肩负了太多技术债时，真的就不愁吗？与其被动地承受痛苦，为何不主动向冗长乏味的无用文档、恶臭难闻的烂代码、迷宫一般无解的遗留系统发起进攻呢？
可有决心发起进攻？倘若你真的愿意，请带上本书，它将是助你冲锋陷阵的冲锋枪与防弹衣，因为打造攻防两端的有力武器就是活文档！
我最初接触到活文档这个概念，是在ThoughtWorks做交付项目的时候。当时，我刚刚加入一个大型项目，被项目经理安排到验收测试组，每天负责编写Cucumber验收测试。对于每个验收测试，我都按照Specification的方式编写。由自然语言组成的测试文档，不仅帮助我们梳理了业务需求，还有效地保护了实现代码。
我做得最为成功的一个项目则严格实践了BDD，那是为北美一家医疗行业的头部企业开发医疗内容管理系统。当作为开发人员的我领取到用户故事时，团队的需求分析人员与测试人员已经就该用户故事写好了验收测试，而我们的目标是让覆盖了完整业务场景的验收测试从红色变成绿色。在实现层面，我们通过结对按照TDD的节奏进行：分解任务，编写单元测试，让单元测试通过，重构，然后编写下一个测试……生活继续！
为了追求开发进度，在几个迭代中我们渐渐放松了验收测试的要求。为了尽快将任务卡挪到“已验收”，我们对验收测试的完成采取睁一只眼闭一只眼的态度。没想到惩罚很快就来了！需求变更让我们的修改变得战战兢兢，持续集成的反馈变得不再准确，总是营造出“假装通过”的错觉。幸好，我们在回顾会议上及时发现了这一问题。为了要求开发人员必须实现验收测试，我们甚至调整了看板，在“开发完成”与“测试中”两列之间，特地引入了“验收测试已完成”列。没有完成验收测试，就没有接受手工测试的资格，也就无法交付。
效果不用多说：整个项目的迭代与交付几乎没有延迟；每次演示的功能都让客户感到满意；代码质量高；团队的进度平稳进行，氛围轻松惬意，没有劳心劳力的高强度加班，也没有制造惊心动魄的意外惊喜；技术债虽然存在，但我们总能及时偿还！
阅读本书时，我又回忆起这一成功的项目经历。该项目以及其他成功项目推行的最佳实践在本书都有所体现。本书就像一座宝藏，包含诸多项目取得成功的秘诀，只要你愿意付出成本去学习和接受它们：
如何通过活需求说明推进BDD或者ATDD；
如何通过活文档表现领域知识，并对活知识进行管理；
如何让文档变得自动化，变得能够运行；
如何让文档与代码、设计和架构共同演进。
显然，本书提及的内容已经超越了文档，甚至超越了最初由Gojko Adzic提出的“活文档”概念涵盖的范畴。尤为可喜的是，作者将活文档与领域驱动设计结合起来，详细描述了如何让活文档遵循通用语言，并为此建立“活词汇表”，真实而完整地传递领域知识，并且介绍了如何通过注解（annotation）去表达限界上下文、领域服务、聚合等领域驱动设计的要素和模式。这一理念恰好和我提出菱形对称架构的角色构造型不谋而合——在我的领域驱动设计项目中，正好通过定义诸如@Remote、@Local、@DomainService、@Aggregate、@Port和@Adapter等注解，用以描述角色构造型。这不由得让我生出遇见知音的喜悦之情。
当然，本书对注解的运用不仅限于此。作者提倡“使用注解编写文档”，此时“注解不只是标签”，“使用注解来阐明源代码语义的代码库将成为机器可以解释的数据网”，还可以用注解来“描述决策背后的依据”，支持所谓的“嵌入式学习”。
本书提及的可视化活文档的实践更是给我们打开了一扇崭新的窗户。不是死板的代码逆向工程，而是通过运用诸如Graphviz这样的工具，形成活图表来清晰、直观地呈现软件系统的设计质量与编码质量，如通过代码自动生成六边形架构图、上下文映射图和业务领域概览图等。这些活图表实际上就是活架构文档的重要组成部分。
本书提出了太多真知灼见！咋一看，与传统的软件工程观点相比，一些建议显得有些离经叛道，甚至可能颠覆开发人员沿袭多年的工作习惯。因此，阅读本书需要怀有空杯心态，主动拥抱理念上的变化，然后精炼书中的内容，有选择地推行到自己的团队。软件开发讲究团队精神，一个人的改进抵御不了整个团队坏习惯的侵袭。只有大家都愿意为活文档的创建与演进添砖加瓦，活文档才能展现它推动快乐编程的魅力与“杀敌制胜”的威力。
在阅读本书时，我已经迫不及待地在团队推行了一些小小的变革，譬如通过改进README文件建立常青文档，引入DSL改进代码的可读性，引入提交变更的类型让代码的提交信息更加规范、具备自说明能力。我也正在考虑为领域驱动设计角色构造型引入可视化活文档的实践。总之，我在许多交付项目中已经尝到了活文档的甜头。在读完本书后，我更加坚定地选择为团队引入更多活文档实践。那么，睿智如你，还犹豫什么呢？
张逸
《解构领域驱动设计》作者
2021年1月5日写于冬日暖阳中的蓉城
❀❀❀
限 时 折 扣
为了更能广泛地传播本书，推广「活文档」的理念，出版社特地争取了电商大力度活动，京东和当当均 5 折上新。
数量有限，手慢无！
京东传送门
当当传送门
赠 书 福 利
你写过文档吗？你写文档过程中遇到过哪些坑？你读过同事写的文档吗？用一句话形容一下那种感觉。
挑选 3 位留言有趣或者写文档有痛点的读者， 每人送出《活文档》1 本（编辑手签专有姓名贴纸版）。
活动截止时间：2021 年 3 月 25 日 12：00。
❀❀❀
☼ 屐痕处处：2012年12月1日摄于厦门大学。