代碼與質量的思考與隨筆

讓咱們從正經的聊聊 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.

---

本文同時也發佈在個人前端專欄，歡迎你們關注