作为公司代码委员会 golang 分会的理事，我 review 了很多代码，看了很多别人的 review 评论。发现不少同学 code review 与写出好代码的水平有待提高。在这里，想分享一下我的一些理念和思路。

Code'。知易行难，知行合一难。嘴里要讲出来总是轻松，把别人讲过的话记住，组织一下语言，再讲出来，很容易。绝知此事要躬行。设计理念你可能道听途说了一些，以为自己掌握了，但是你会做么？有能力去思考、改进自己当前的实践方式和实践中的代码细节么？不客气地说，很多人仅仅是知道并且认同了某个设计理念，进而产生了一种虚假的安心感---自己的技术并不差。但是，他根本没有去实践这些设计理念，甚至根本实践不了这些设计理念，从结果来说，他懂不懂这些道理/理念，有什么差别？变成了自欺欺人。

代码，是设计理念落地的地方，是技术的呈现和根本。同学们可以在 review 过程中做到落地沟通，不再是空对空的讨论，可以在实际问题中产生思考的碰撞，互相学习，大家都掌握团队里积累出来最好的实践方式！当然，如果 leader 没时间写代码，仅仅是 review 代码，指出其他同学某些实践方式不好，要给出好的实践的意见，即使没亲手写代码，也是对最佳实践要有很多思考。

为什么同学们要在 review 中思考和总结最佳实践

我这里先给一个我自己的总结：所谓架构师，就是掌握大量设计理念和原则、落地到各种语言及附带工具链（生态）下的实践方法、垂直行业模型理解，定制系统模型设计和工程实践规范细则。进而控制 30+万行代码项目的开发便利性、可维护性、可测试性、运营质量。

厉害的技术人，主要可以分为下面几个方向：

掌握很多技巧，以及发现技巧一系列思路，比如很多编程大赛，比的就是这个。但是，这个对工程，用处好像并不是很大。

比如约翰*卡马克，他创造出了现代计算机图形高效渲染的方法论。不论如果没有他，后面会不会有人发明，他就是第一个发明了。1999 年，卡马克登上了美国时代杂志评选出来的科技领域 50 大影响力人物榜单，并且名列第 10 位。但是，类似的殿堂级位置，没有几个，不够大家分，没我们的事儿。

这个是大家都可以做到，按照上面架构师的定义。在这条路上走得好，就能为任何公司组建技术团队，组织建设高质量的系统。

从上面的讨论中，可以看出，我们普通工程师的进化之路，就是不断打磨最佳实践方法论、落地细节。

在讨论什么代码是好代码之前，我们先讨论什么是不好的。计算机是人造的学科，我们自己制造了很多问题，进而去思考解法。

说到组合，还有一个关系很紧密的词，叫插件化。大家都用 vscode 用得很开心，它比 visual studio 成功在哪里？如果 vscode 通过添加一堆插件达到 visual studio 具备的能力，那么它将变成另一个和 visual studio 差不多的东西，叫做 vs studio 吧。大家应该发现问题了，我们很多时候其实并不需要 visual studio 的大多数功能，而且希望灵活定制化一些比较小众的能力，用一些小众的插件。甚至，我们希望选择不同实现的同类型插件。这就是组合的力量，各种不同的组合，它简单，却又满足了各种需求，灵活多变，要实现一个插件，不需要事先掌握一个庞大的体系。体现在代码上，也是一样的道理。至少后端开发领域，组合，比 OOP，'香'很多。

原则 6 吝啬原则: 除非确无它法, 不要编写庞大的程序

可能有些同学会觉得，把程序写得庞大一些才好拿得出手去评 T11、T12。leader 们一看评审方案就容易觉得：很大，很好，很全面。但是，我们真的需要写这么大的程序么？

我又要说了"那么，古尔丹，代价是什么呢？"。代价是代码越多，越难维护，难调整。C 语言之父 Ken Thompson 说"删除一行代码，给我带来的成就感要比添加一行要大"。我们对于代码，要吝啬。能把系统做小，就不要做大。腾讯不乏 200w+行的客户端，很大，很牛。但是，同学们自问，现在还调整得动架构么。手 Q 的同学们，看看自己代码，曾经叹息过么。能小做的事情就小做，寻求通用化，通过 duck interface(甚至多进程，用于隔离能力的多线程)把模块、能力隔离开，时刻想着删减代码量，才能保持代码的可维护性和面对未来的需求、架构，调整自身的活力。客户端代码，UI 渲染模块可以复杂吊炸天，非 UI 部分应该追求最简单，能力接口化，可替换、重组合能力强。

落地到大家的代码，review 时，就应该最关注核心 struct 定义，构建起一个完备的模型，核心 interface，明确抽象 model 对外部的依赖，明确抽象 model 对外提供的能力。其他代码，就是要用最简单、平平无奇的代码实现模型内部细节。

原则 7 透明性原则: 设计要可见，以便审查和调试

首先，定义一下，什么是透明性和可显性。

"如果没有阴暗的角落和隐藏的深度，软件系统就是透明的。透明性是一种被动的品质。如果实际上能预测到程序行为的全部或大部分情况，并能建立简单的心理模型，这个程序就是透明的，因为可以看透机器究竟在干什么。

如果软件系统所包含的功能是为了帮助人们对软件建立正确的'做什么、怎么做'的心理模型而设计，这个软件系统就是可显的。因此，举例来说，对用户而言，良好的文档有助于提高可显性；对程序员而言，良好的变量和函数名有助于提高可显性。可显性是一种主动品质。在软件中要达到这一点，仅仅做到不晦涩是不够的，还必须要尽力做到有帮助。"

我们要写好程序，减少 bug，就要增强自己对代码的控制力。你始终做到，理解自己调用的函数/复用的代码大概是怎么实现的。不然，你可能就会在单线程状态机的 server 里调用有 IO 阻塞的函数，让自己的 server 吞吐量直接掉到底。进而，为了保证大家能对自己代码能做到有控制力，所有人写的函数，就必须具备很高的透明性。而不是写一些看了一阵看不明白的函数/代码，结果被迫使用你代码的人，直接放弃了对掌控力的追取，甚至放弃复用你的代码，另起炉灶，走向了'制造重复代码'的深渊。

透明性其实相对容易做到的，大家有意识地锻炼一两个月，就能做得很好。可显性就不容易了。有一个现象是，你写的每一个函数都不超过 80 行，每一行我都能看懂，但是你层层调用，很多函数调用，组合起来怎么就实现了某个功能，看两遍，还是看不懂。第三遍可能才能大概看懂。大概看懂了，但太复杂，很难在大脑里构建起你实现这个功能的整体流程。结果就是，阅读者根本做不到对你的代码有好的掌控力。

可显性的标准很简单，大家看一段代码，懂不懂，一下就明白了。但是，如何做好可显性？那就是要追求合理的函数分组，合理的函数上下级层次，同一层次的代码才会出现在同一个函数里，追求通俗易懂的函数分组分层方式，是通往可显性的道路。

当然，复杂如 linux 操作系统，office 文档，问题本身就很复杂，拆解、分层、组合得再合理，都难建立心理模型。这个时候，就需要完备的文档了。完备的文档还需要出现在离代码最近的地方，让人'知道这里复杂的逻辑有文档'，而不是其实文档，但是阅读者不知道。再看看上面 golang 标准库里的 http.Request，感受到它在可显性上的努力了么？对，就去学它。

原则 10 通俗原则: 接口设计避免标新立异

设计程序过于标新立异的话，可能会提升别人理解的难度。

一般，我们这么定义一个'点'，使用 x 表示横坐标，用 y 表示纵坐标：

很好，你用词很精准，一般人还驳斥不了你。但是，多数人读你的 VerticalOrdinate 就是没有读 X 理解来得快，来得容易懂、方便。你是在刻意制造协作成本。

上面的例子常见，但还不是最小立异原则最想说明的问题。想想一下，一个程序里，你把用'+'这个符号表示数组添加元素，而不是数学'加'，'result := 1+2' --> 'result = []int{1, 2}'而不是'result=3'，那么，你这个标新立异，对程序的破坏性，简直无法想象。"最小立异原则的另一面是避免表象相似而实际却略有不同。这会极端危险，因为表象相似往往导致人们产生错误的假定。所以最好让不同事物有明显区别，而不要看起来几乎一模一样。" -- Henry Spencer。

你实现一个 db.Add函数却做着 db.AddOrUpdate的操作，有人使用了你的接口，错误地把数据覆盖了。

原则 11 缄默原则: 如果一个程序没什么好说的，就沉默

req.String)'，非常害怕自己信息打印得不够。害怕自己不知道程序执行成功了，总要最后'log("success")'。但是，我问一下大家，你们真的耐心看过别人写的代码打的一堆日志么？不是自己需要哪个，就在一堆日志里，再打印一个日志出来一个带有特殊标记的日志'log("this_is_my_log_" + xxxxx)'？结果，第一个作者打印的日志，在代码交接给其他人或者在跟别人协作的时候，这个日志根本没有价值，反而提升了大家看日志的难度。

一个服务一跑起来，就疯狂打日志，请求处理正常也打一堆日志。滚滚而来的日志，把错误日志淹没在里面。错误日志失去了效果，简单地 tail 查看日志，眼花缭乱，看不出任何问题，这不就成了'为了捕获问题'而让自己'根本无法捕获问题'了么？

沉默是金。除了简单的 stat log，如果你的程序'发声'了，那么它抛出的信息就一定要有效！打印一个 log('process fail')也是毫无价值，到底什么 fail 了？是哪个用户带着什么参数在哪个环节怎么 fail 了？如果发声，就要把必要信息给全。不然就是不发声，表示自己好好地 work 着呢。不发声就是最好的消息，现在我的 work 一切正常！

"设计良好的程序将用户的注意力视为有限的宝贵资源，只有在必要时才要求使用。"程序员自己的主力，也是宝贵的资源！只有有必要的时候，日志才跑来提醒程序员'我有问题，来看看'，而且，必须要给到足够的信息，让一把讲明白现在发生了什么。而不是程序员还需要很多辅助手段来搞明白到底发生了什么。

每当我发布程序 ，我抽查一个机器，看它的日志。发现只有每分钟外部接入、内部 rpc 的个数/延时分布日志的时候，我就心情很愉悦。我知道，这一分钟，它的成功率又是 100%，没任何问题！

原则 12 补救原则: 出现异常时，马上退出并给出足够错误信息

其实这个问题很简单，如果出现异常，异常并不会因为我们尝试掩盖它，它就不存在了。所以，程序错误和逻辑错误要严格区分对待。这是一个态度问题。

'异常是互联网服务器的常态'。逻辑错误通过 metrics 统计，我们做好告警分析。对于程序错误 ，我们就必须要严格做到在问题最早出现的位置就把必要的信息搜集起来，高调地告知开发和维护者'我出现异常了，请立即修复我!'。可以是直接就没有被捕获的 panic 了。也可以在一个最上层的位置统一做好 recover 机制，但是在 recover 的时候一定要能获得准确异常位置的准确异常信息。不能有中间 catch 机制，catch 之后丢失很多信息再往上传递。

很多 Java 开发的同学，不区分程序错误和逻辑错误，要么都很宽容，要么都很严格，对代码的可维护性是毁灭性的破坏。"我的程序没有程序错误，如果有，我当时就解决了。"只有这样，才能保持程序代码质量的相对稳定，在火苗出现时扑灭火灾是最好的扑灭火灾的方式。当然，更有效的方式是全面自动化测试的预防：）

前面提了好多思考方向的问题。大的原则问题和方向。我这里，再来给大家简单列举几个细节执行点吧。毕竟，大家要上手，是从执行开始，然后才是总结思考，能把我的思考方式抄过去。下面是针对 golang 语言的，其他语言略有不同。以及，我一时也想不全我所执行的 所有细则，这就是我强调'原则'的重要性，原则是可枚举的。

• 对于代码格式规范，100%严格执行，严重容不得一点沙。
• 文件绝不能超过 800 行，超过，一定要思考怎么拆文件。工程思维，就在于拆文件的时候积累。
• 函数对决不能超过 80 行，超过，一定要思考怎么拆函数，思考函数分组，层次。工程思维，就在于拆文件的时候积累。
• 代码嵌套层次不能超过 4 层，超过了就得改。多想想能不能 early return。工程思维，就在于拆文件的时候积累。

下面这个就是 early return，把两端代码从逻辑上解耦了。

• 从目录、package、文件、struct、function 一层层下来 ，信息一定不能出现冗余。比如 file.FileProperty 这种定义。只有每个'定语'只出现在一个位置，才为'做好逻辑、定义分组/分层'提供了可能性。
• 多用多级目录来组织代码所承载的信息，即使某一些中间目录只有一个子目录。
• 随着代码的扩展，老的代码违反了一些设计原则，应该立即原地局部重构，维持住代码质量不滑坡。比如:拆文件；拆函数；用 Session 来保存一个复杂的流程型函数的所有信息；重新调整目录结构。
• 基于上一点考虑，我们应该尽量让项目的代码有一定的组织、层次关系。我个人的当前实践是除了特别通用的代码，都放在一个 git 里。特别通用、修改少的代码，逐渐独立出 git，作为子 git 连接到当前项目 git，让 goland 的 Refactor 特性、各种 Refactor 工具能帮助我们快速、安全局部重构。
• 自己的项目代码，应该有一个内生的层级和逻辑关系。flat 平铺展开是非常不利于代码复用的。怎么复用、怎么组织复用，肯定会变成'人生难题'。T4-T7 的同学根本无力解决这种难题。
• 如果被 review 的代码虽然简短，但是你看了一眼却发现不咋懂，那就一定有问题。自己看不出来，就找高级别的同学交流。这是你和别 review 代码的同学成长的时刻。
• 日志要少打。要打日志就要把关键索引信息带上。必要的日志必须打。
• 有疑问就立即问，不要怕问错。让代码作者给出解释。不要怕问出极低问题。
• 不要说'建议'，提问题，就是刚，你 pk 不过我，就得改！
• 请积极使用 trpc。总是要和老板站在一起！只有和老板达成的对于代码质量建设的共识，才能在团队里更好地做好代码质量建设。
• 消灭重复！消灭重复！消灭重复！

最后，我来为'主干开发'多说一句话。道理很简单，只有每次被 review 代码不到 500 行，reviewer 才能快速地看完，而且几乎不会看漏。超过 500 行，reviewer 就不能仔细看，只能大概浏览了。而且，让你调整 500 行代码内的逻辑比调整 3000 行甚至更多的代码，容易很多，降低不仅仅是 6 倍，而是一到两个数量级。有问题，在刚出现的时候就调整了，不会给被 review 的人带来大的修改负担。

《unix 编程艺术》

建议大家把这本书找出来读一读。特别是，T7 及更高级别的同学。你们已经积累了大量的代码实践，亟需对'工程性'做思考总结。很多工程方法论都过时了，这本书的内容，是例外中的例外。它所表达出的内容没有因为软件技术的不断更替而过时。

佛教禅宗讲'不立文字'(不立文字，教外别传，直指人心，见性成佛)，很多道理和感悟是不能用文字传达的，文字的表达能力，不能表达。大家常常因为"自己听说过、知道某个道理"而产生一种安心感，认为"我懂了这个道理"，但是自己却不能在实践中做到。知易行难，知道却做不到，在工程实践里，就和'不懂这个道理'没有任何区别了。

曾经，我面试过一个别的公司的总监，讲得好像一套一套，代码拉出来遛一遛，根本就没做到，仅仅会道听途说。他在工程实践上的探索前路可以说已经基本断绝了。我只能祝君能做好向上管理，走自己的纯管理道路吧。请不要再说自己对技术有追求，是个技术人了！

所以，大家不仅仅是看看我这篇文章，而是在实践中去不断践行和积累自己的'教外别传'吧。