代码与质量的思考与随笔

让咱们从正经的聊聊 API 设计开始

在上一篇文章里，我建议 API 应该围绕消费端需求展开设计。“以消费者为中心”只是我我的的经验之谈。可是若是你有心去发掘，你会找到更多 API 相关的设计指南

在 《Designing Web APIs》 一书的第四章里，做者提出了他认为的 Design Best Practices. 包括如下几点：

• Designing for Real-Life Use Cases
• Designing for a Great Developer Experience
  • Make it Fast and Easy to Get Started
  • Work Toward Consistency
  • Make Troubleshooting Easy
  • Make Your API Extensible

在实际的叙述过程当中，他举了几个来自专业人士的建议：

When we asked Ido Green, developer advocate at Google, what makes an API good, his top answer was focus: “The API should enable developers to do one thing really well. It’s not as easy as it sounds, and you want to be clear on what the API is not going to do as well.”

No matter how carefully we design and build our core API, developers continue to create products we’d never expect. We give them the freedom to build what they like. Designing an API is much like designing a transportation net‐work. Rather than prescribing an end state or destination, a good API expands the very notion of what’s possible for developers. —Romain Huet, head of developer relations at Stripe

Don’t overcomplicate your API and don’t future-proof it too much. Often by future-proofing your API, you make it too generic and/or too complex. Developers building applications on (or using) your platform are building stuff for the “now.” They like to move quickly and are not always thinking 10 steps ahead. Your API should cater to this mindset. —Yochay Kiriaty, Azure principal program manager at Microsoft

他们更倾向于关注当下，关注开发者。而并不是以提供者为中心

而在 《APIs: A Strategy Guide》 一书第五章 Key Design Principles for APIs 中做者也一样花费了一章的篇幅来表述他认为的 API 设计原则。其中非技术性的原则有

• Design APIs for Specific Audiences
  • Designing for Developers
  • Designing for Application Users
• Best Practices for API Design
  • Differentiate Your API
  • Make Your API Easy to Try and Use
  • Make Your API Easy to Understand
  • Don't Do Anything Weird
  • Less is More
  • Target a Specific Developer Segment

在这两本书中，做者们提倡一种“渐进式”和“基于反馈”的开发模式：

Successful APIs often start with the absolute minimum amount of functionality, and then add functions slowly over time, as feedback is collected.

When talking to companies in the midst of launching an API, we often ask “Who are your target audiences?” If they answer by saying “Everybody,” we get worried. Similarly, if we ask them “What kinds of apps do you expect to see built?”, we get worried if their answer is, “All kinds.” Why? It’s really hard to create an API to meet the demands of every possible constituent and every possible use case. And even if you had the perfect API, you can’t market effectively to all these segments.

若是把以上种种称之为理想流派的话， 在真实的世界里，我不止一次听到的是另外一种声音是：接口应该是尽量稳定且一成不变的基础服务，包容来自不一样客户端的消费。这又回到了上一篇文章我反对的起点：即一种大而全的渴望一劳永逸的 API 设计。

可是咱们不该该批评这种作法，你能够把这种作法看成称之为现实流派，这实际上是目前绝大部分互联网公司的现状。想象一下你随便在公司找一位研发同窗和他聊咱们应该精细化迭代和运营 API ，虽然他嘴上不说可是他的表情已经仍不住想告诉你：你疯了吧。这里的“疯”隐射的是不现实：一方面咱们没有足够的时间和人力分配到这样的工做中来；另外一方面即便咱们这么作了，咱们又能从中获得什么呢？KPI 依然没有完成，用户增加依然停滞不前。因此折（底）中（线）的方案是，简单粗暴，能用便是好用。更重要的是，你身临其境的看到这样的 API 开发也是奏效的。

关于 API 设计的讨论此为止。在这里我想引出另外一个问题：既然咱们理想和现实如此分裂，甚至无力反抗现实时，咱们是否仍然关心设计？

“关心”这个词很微妙，它同时表达了两层含义：Why and How

---

在《The Mythical Man Month》一书第一章的开头，做者 Brooks 对 Program 和 Programming Product 进行了区分，前者能够仅仅是程序员我的在车库里的产出，然后者则是

This is a program that can be run,tested, repaired, and extended by anybody. It is usable in many operating environments, for many sets of data. To become a generally usable programming product, a program must be written in a generalized fashion.

做者之因此对这两类程序作出不一样的划分，是想说明它们的生产代价不一样， Programming Product 的成本至少是 Program 的三倍以上 。而在我看来，它们存在着性质上的不一样。

天天你都能在掘金社区或者 Medium 网站上看到诸如 Vue + Webpack + Express + GraphQL 全家桶组合教程。Wow，全栈、 最新最夯的技术、融合官方推荐的最佳实践，无懈可击简直无敌了。新生、完美、纯净，但它只是一个 DEMO。我把它划分为 Program

而实际上这么多年我天天工做中须要维护的前端系统像是变异的怪物：可能 RequireJS 和 ES6 共存，可能 Grunt 和 Webpack 共存，还有许多团队老大写的半死不活的框架也被揉入其中，致使每次增改代码都如履薄冰。丑陋、臃肿、禁锢、可它是实实在在的线上产品。我把它归类为 Programming Product

而它们的根本不一样点之一，就是代码的可维护性不一样。绝不客气的说 DEMO 一般是一次性的，我尝试过了，证实它们的组合是可行的，再证实我能力就足够了。但线上产品中，你找不到任何一个不须要二次维护的程序。

软件行业有几条公认的真理：

• 惟一不变的就是变化自己
• 代码不可避免的会走向腐烂。

因此大家看到的全部“好”的东西，好比重构、TDD、DDD都是在尽量的减缓和改善代码的腐烂，设计也是。

腐烂并不意味着不可用，而是意味着维护成本极高。可是在互联网公司吊诡的事情是，维护性高并不算是一个问题，或者说它是个问题但不在解决的范围以内，一方面相比这样没法量化而且只有基层关心的与上线产品没有半毛钱关系的问题，跑马圈地的速度更显重要；另外一方面若是由于员工离职率高真的到了无人能维护的地步，重写一般是最佳的选择。我很难想象一个系统在互联网公司内部可以维护 5 年乃至 10 年以上。即便有一般的结果也是名不副实，它确实坚挺了不少年，可是已经不知道经历了多少次重写多少代团队的手了。However, 这样的作法无可厚非。

---

我不相信代码质量存在文化相对主义，代码质量是有绝对的好坏之分的。比如你不管如何都没法说服本身这段五百行的函数是一段好代码，不管是在任何编程语言中。

认可吧虽然咱们每一个人都不但愿接手维护的是烂代码，但事与愿违老是在发生。以致于每次我都忍不住打开 git blame 看一眼到底是谁的“好事”，而后默默把这我的记在本身的小本本上，也不免有几回发现是本身

可是你有没有想过，咱们为何要把代码写好？

我能够简单粗暴的回答没有为何，这是职业道德。不管从事任何职业若是凡事只想敷衍了事就是不对的。可是站在软件工程的角度上看写好代码可以让程序维护性更好，仅此而已。

仅此而已，却难以上青天。

你可能会反驳我上面刚刚不是说了绝大部分公司不在意程序的可维护性吗？站在公司的视角的确如此，但如今你我都不是公司的经营者。做为程序员此时此刻你是在意的，我也是在意的，咱们都承认这件事，这就够了。

对我的而言这还关乎看来这关乎程序员的 respect —— 什么是 respect ?

若是你读过相似于 《Peopleware》之类 IT 企业管理的图书的话，你会发现 IT 团队管理和传统的企业管理有很是大的不一样。有一篇颇有意思的文章 《Opinion: The unspoken truth about managing geeks》 戳破了程序员不一样与传统公司员工的另外一类心态：

Few people notice this, but for IT groups respect is the currency of the realm. IT pros do not squander this currency.

Gaining respect is not a matter of being the boss and has nothing to do with being likeable or sociable; whether you talk, eat or smell right; or any measure that isn't directly related to the work. The amount of respect an IT pro pays someone is a measure of how tolerable that person is when it comes to getting things done, including the elegance and practicality of his solutions and suggestions.

IT pros always and without fail, quietly self-organize around those who make the work easier, while shunning those who make the work harder, independent of the organizational chart.

While everyone would like to work for a nice person who is always right, IT pros will prefer a jerk who is always right over a nice person who is always wrong. Wrong creates unnecessary work, impossible situations and major failures. Wrong is evil, and it must be defeated. Capacity for technical reasoning trumps all other professional factors, period.

程序员打心底有一种特殊 “尊重（respect）” 观念，这种对人的尊重和人的地位、职位、爱好、谈吐一点关系都没有，只和这我的搞不搞得定事情有关。 他们会自发自然的围绕在这种人身边和他一块儿共事，哪怕他是一个混蛋，只要他拥有把问题处理的有好又漂亮的能力。

很显然写出烂代码不是一种可以赢得尊重的行为，相反可能你反而会被边缘化。（固然也不排除在某些公司会劣币驱逐良币）

而设计是另外一种形式的编码，从架构的角度影响着整个程序的可维护性。若是说架构须要设计，数据库须要设计，程序须要设计，为何 API 不须要设计？

---

另外一个 DEMO 的局限性在于，它没法体现不管是编程者仍是技术自己解决现实问题的能力。例如任何一个新进框架总喜欢用 TODO APP 来证实本身的可行性和新特性。可是一个离线的有限个组件的应用和实际上它要解决的用户场景相差太远了。量变产生质变是一个说烂了的梗，但现实的状况就是如此。维护 1 个组件和维护 1000 个组件的方法是不一样的；要解决一个用户和解决一万个用户的问题是不一样的。以及当引入这个技术栈时，须要关心对团队会有什么样的影响，产能爬坡的阶段须要持续多久。

我我的的感觉是，随着须要解决问题的复杂度加深和 case 定制化，我的经验乃至大众经验可以带来的帮助是愈来愈少。而你天天又不得不面对不一样的技术方案决策，那么你如何驱动你的决策？至少须要一条原则，哪怕这条原则只是底线而已。说的轻松点，原则决定你走哪条路；说的严肃点，原则决定了你什么能作什么不能作。公司是这样，产品是这样，代码也是这样

咱们承认了万物皆可设计，可是设计的原则应该是什么？

我最近看了两本很是好的书《Code Simplicity》和《Understanding Software》，它们不是在谈某一门编程语言或者编程技术，而是聊编程这件事。我很是承认书中做者提出的软件设计的终极目标：帮助他人。即便做为程序员你编写的程序类库，它们也是为程序员服务的，程序员也是人。

更有意思的事情是，做者认为一我的写出优秀软件的潜力，彻底取决于他在多大程度上理解了 “帮助其余人” 的思想。因此当你下次想放松下来写一段烂代码时，多想一想这件事，天然就被劝退了

这篇文章我只是想抛出把代码写好这件事很重要，而至于如何能写好的代码，这两本书里给出很好的答案。以及你能参考的各类最佳实践和方法论都是绝佳的材料

---

我最近参加了公司组织的几场培训，关于不一样方面的能力建设。但以后的某一天我忽然明白哪怕我参与了整整一周甚至一个月的培训，也不表明我马上拥有了对应的能力。我保证各位的每一位领导公司都为他们提供了相似于提高领导力的培训，可是咱们见过的混蛋领导还少吗。

程序员也是同样，会敲代码和合格的程序员根本就是两码事，会使用框架和合格的程序员也是两码事。那种已经有几年工做经验可是代码依然不堪入目的人咱们也还见得少吗？在工做这么多年以后老是会不由在想，我和坐在我斜对角那个维护着相同代码库的大三实习生相比竞争力在哪? 若是个人团队须要招聘新的成员，除了框架的熟练程度之外我还应该考察哪些方面？让程序跑起来一点都不难，这是底线。难的是如何让程序跑的更快，跑的更久，甚至经过一个程序让整个系统变得更好。

最后我想对我开头提出的问题本身作一个回答：咱们应该认可和尊重理想流派的正当性。可是再实施层面，若是环境压迫着你必须走现实流派我也理解你。若是有机会的话，请尽量的向理想流派靠拢，让代码变得更好

关于这一点在 《Understanding Software》一书当中有一段比喻特别好：

You have something like a house on fire, except that the house is the size of several mountains and it's all on fire all the time. You need to figure out which part of the "mountain" or "house " that you actually need right now, and get that into good shape so that it can be "used", on a series of small steps

Your first goal is to get the system into a place where it's getting better overtime, instead of getting worse.

---

本文同时也发布在个人前端专栏，欢迎你们关注