软件开发

花了一个多月读完了这本《架构整洁之道》，跟《代码整洁之道》、《程序员的职业素养》算是一个 Clean 系列，每一本读来都很有启发。这本《架构整洁之道》有些地方看得还挺迷糊，值得一读再读。 概述、编程范式 设计与架构没有任何区别。一丁点区别都没有！软件架构的终极目标是，用最小的人力成本来满足构建和维护该系统的需求。 ...

这本书的英文名是 The Clean Coder, 中文译名是《代码整洁之道：程序员的职业素养》，跟《代码整洁之道》是同一个作者。这本书与具体的代码技巧关系不大，主要就讲了一件事——如何做一名专业的程序员。 挺薄一本书，内容都是日常所见，加上翻译也不错，所以读起来感觉轻松流畅。书中多数内容早已在实践，我印象最深刻的是这样几点：专业人士的态度，要重视测试，如何预估项目，以及对「流态区」的看法。 ...

apiDoc 可以通过文本生成体验良好的 API 文档页面，这些文本可以以注释的形式放在代码里，apiDoc 读取源码注释，就可以生成页面了，当然也可以与代码分开，写一些全是注释的文档，作为 apiDoc 生成文档页面的「源文件」。 ...

摘录了一些内容，跟这些内容在书中出现的顺序不同，打散又整理了一下。除了斜体字部分，都是对原书的引用。 应该有的态度 程序员遵从不了解混乱风险的经理的意愿，也是不专业的做法。 做好自己的事，尊重自己的手艺，写干净的代码。 糟糕的代码引发混乱！别人修改糟糕代码时，往往会越改越烂。 碰到过“从跟上就烂”的项目代码，对这种项目的改造往往较为困难，成本很高，甚至不如推到重来。 签入的代码，要比签出时整洁一点。 代码应当讲述事实，不引人猜测。 整洁的代码总是看起来像是某位特别在意它的人写的。 聪明程序员和专业程序员之间的区别在于，专业程序员了解：明确是王道。 言到意到。意到言到。 如果同一段代码反复出现，就表示某种想法未在代码中得到良好的体现。 一些细节做法 （变量名的）名称长短与其作用域大小相对应。 变量声明应尽可能靠近其使用位置。 调用者应该尽可能放在被调用者上面。 应该避免我们的代码过多地了解第三方代码中的特定信息。依靠你能控制的东西，好过依赖你控制不了的东西，免得日后受它控制。 使用第三方库时，跟第三方库”划清界线“。一个可行的做法是把第三方库提供的接口再封装一层。业务代码只有自己的这层封装打交道，这样一来，如果要换用其他库，只改这个封装层，以此减少跟第三库的耦合以及依赖。 看到注释掉的代码，就删掉它。 否定式要比勘定式难明白一些。所以，尽可能将条件表示为肯定形式。 函数 函数的第一规则是要短小。第二条规则是还要更短小。 函数应该做一件事。做好这件事。只做这一件事。问题在于很难知道那件该做的事是什么。 要确保函数只做一件事，函数中的语句都要在同一抽象层级上。 在这个函数里做的事情，是同一个抽象层上的步骤，那么这个函数是只做了一件事。 函数越短小、功能越集中，就越便于取个好名字。 函数要么做什么事，要么回答什么事，但二者不可得兼。 错误处理 最好把 try 和 catch 代码块的主体部分抽离出来，另外形成函数。 函数应该只做一件事。错误处理就是一件事。因此，处理错误的函数不该做其他事。这意味着，如果关键字 try 在某个函数中存在，它就该是这个函数的第一个单词，而且在 catch/finally 代码块后面也不该有其他内容。 错误处理很重要，但如果它搞乱了代码逻辑，就是错误的做法。 测试 没有测试的代码不干净。 不可测试的系统不可验证。不可验证的系统，绝不应部署。 紧耦合的代码难以编写测试。 编写测试引致更好的设计。 写测试能够反过来逼着人写出更好的代码。 测试消除了对清理代码就会破坏代码的恐惧。 整洁的测试有什么要素？有三个要素：可读性，可读性和可读性。在单元测试中，可读性甚至比在生成代码中还重要。 独立测试应该相互独立。某个测试不应为下一个测试设定条件。 让测试具有表达力并短小精悍。

上周末翻完了《Go 语言实战》这本书，还不错，篇幅不大，内容实用。书中有很多内容是这样写的：先给出一大段代码，然后一点一点拆解分析，稍微有些啰嗦。我先把 A Tour of Go 过了一遍，再看这本书算是更深入了一点。 ...