如何讀文檔？

01-29

前言

今天收到一份微博私信，問我之前量產型炮灰工程師中說一個良性的學習循環需要自己尋找線上資源學習、讀文檔等等，這些都沒有在培訓班中被學到。那怎樣才能比較好的讀文檔呢？不分享一下的話，老說我是光破不立，光批評別人自己卻沒有任何解決。那麼我還是來分享一下我讀文檔的思路吧。

大局入手

首先，這裡的讀文檔並不局限於介面文檔，介面文檔更像是工具書，這裡的文檔泛指圍繞代碼周邊的文字說明。你要學習一門語言、框架或者某個工具，肯定不是因為它是一個工具所以你就學。框架的開發者也不會是因為想寫一個框架所以就寫一個框架。凡事都一定有它的理由，一個語言、框架、工具的存在一定是為了解決某一個或某一類特定的問題而存在的。同一個類型的不同的語言、框架、工具之所以會不同，是因為他們試圖在解決不同的問題，或者某個工具正在解決另一個不能解決的某種問題。這時候作者的想法是尤為重要的，如果弄清楚這方面想法對於你的學習自然是事半功倍的。

作者的想法在哪裡？

在官方的教程、官方的概述里。對於 Ruby 來說，其官網的關於頁短短一頁就幾乎解釋了什麼是 Ruby，Ruby 和其他語言的不同：

Ruby 從多門語言中學習了經驗，注重其平衡性
兼具函數式編程和命令式編程特色
Ruby 試著讓語言更自然，而不是更簡單
Ruby 將一切視為對象
Ruby 允許用戶修改語言自身
Ruby 的閉包具有極強表現力
Ruby 對象只提供單繼承，但支持混入
Ruby 的變數系統
Ruby 的其他細節

有了這些大綱，這對於你理解 Ruby 中的很多表現就有了很大的認識。接著再去看 Ruby Users Guide 或者 Programming Ruby 就會有很大的幫助。

了解變化

在學習了一個東西的大綱和入門教程之後，大版本的更新記錄是文檔中非常重要，卻是最容易被忽略的部分。

比如 Qt 在 4.8 版本中引入了 QML。我相信很多公司都號稱使用 Qt 做跨平台界面開發，卻很少注意 Qt 本身的變化。很多公司 Qt 5 的代碼寫得和 Qt 3 也沒有什麼區別。QML 的引入對於界面的繪製，事件的綁定和數據的刷新提供了一整套 DSL，從而讓整個開發變得容易和可讀太多。大版本的更新記錄很重要是因為之所以會有版本更新一定是因為之前寫的不好，需要改進。如果只是從細節入手看介面，舊介面通常會為了兼容性而保留，這時候並不能宏觀地知道作者想讓你怎麼用。

比如 Ruby 在 2.3.0 中引入了 Safe Navigation Operator &.，其類似於 C# 中的 ?.。Ruby 的 ActiveSupport 庫中本來其實有類似的語法，它是 Object#try。但 Ruby 作者將這個東西從一個語義層面提升到了一個語法層面，體現了作者在這方面的重視。這是 Ruby 所說的注重其平衡性的一種體現。當你了解了作者的這種想法，你才能寫出更好的代碼，顯然 Ruby 作者對 Ruby 的理解是相當深刻的。

再比如 HTML5 中引入了 WebSocket API，顯然就是來解決 Web 雙工實時通訊的問題的。如果放著這樣的 API 不用，還在使用輪詢，甚至在瀏覽器上做一些 tricks 來實現更長的連接，不但是浪費資源，更是浪費自己的精力。

實踐與細節

了解了框架的設計思路，了解了基本的使用方法，接下來才可以看介面文檔。這時候你已經有了對框架的基本理解，你就知道自己需要看什麼。可以結合一個自己要做的項目邊寫邊看。需要用到什麼具體的模塊，就去查這個模塊的所有 API。這通常查詢起來會比較方便。當然光看 API 文檔只是對框架的使用，還是不夠的。一個好的項目不只是使用的優雅，更是管理的藝術。項目要管理得好更需要對項目做正確的抽象，這時候再去多看看這個框架的一些好的項目的開源實現，學習一下。之後就對整個框架不僅僅是熟悉使用了，更是有了大局上的認知，使用起來比單純熟悉語法要好很多。

看別人的代碼的思路其實和看文檔是一樣的，不要從細節入手，只會讓自己「亂花漸欲迷人眼」。從大局入手，了解作者的實現思路，然後找出實現的最主要的抽象的部分，再慢慢去啃細節的實現自然會比一行一行讀容易許多。

最重要的是

寫代碼不是默寫，沒有人不讓你邊寫邊搜邊找。讀文檔的關鍵是要在出了問題後知道自己要找什麼，去哪裡找。學習不是閉門造車，要多培養自學的能力，是為了讓自己在脫離別人的教學之後知道自己怎麼學，去哪裡學。計算機軟體行業是一個快速更迭的行業，只有讓自己始終在學習，才能不至於在這個行業中落後。