前端工程師到底為什麼要寫文件？

Thu Nov 18 2021

工程師最討厭的兩件事：

別人不寫文件

寫文件

身為一位前端工程師，其實我在職涯的初期對於「文件撰寫」這件事一直有一種很抽象的感覺，我不知道前端工程師究竟要寫什麼文件。

畢竟大多數的新手前端所開發、接觸的產品都是比較偏向大眾取向的，這種情況下大多數的產品是不需要為使用者撰寫「說明文件」的。

直到後來我接觸了比較大型的專案，與其他的前端工程師共同協作過後，才開始體會到文件的價值。

# 文件有哪幾種

說到文件，首先要釐清的就是這份文件到底是 「寫給誰看的」。

如果是為了使用者而寫的我稱為說明文件，這類型的文件講白了就是使用說明書，目的是讓產品的使用者知道你的產品究竟該如何使用。

這種文件常見的範例就是我們常使用的框架、套件，例如 React、Vue 的官方文件，目的就是讓我們這些開發者（使用者）知道套件該如何使用。

再說一遍，仔細看文檔。

Evan You commented on 2 Apr 2016

還有一種就是寫給你的同事或未來的自己看的，這種我稱之為規格文件 Spec，這種文件在開發前的目的，就是對需求、架構先做一個宏觀的分析，透過這份文件讓 RD 與 PM、QA 等不同的角色產生共識。

這其實是一個沒有標準答案的問題，但我覺得比較好的方式是透過共筆的模式，由 PM 統整開發的需求，RD 分析需求的影響層級、預定的實作，而 QA 則擅長把需求的細節給完善。

如果在團隊的開發中能這樣各司其職，並且在開發早期就進行這樣的資訊同步，可以大大的提升開發效率，減少了後續改動架構的風險，也避免不必要的 Bug 產生。

同時這樣的文件也會是一個記錄，可以在開發階段將文件的連結記錄到 git commit message 裡面，這樣即使在未來遇到需求變更的狀況，也可以快速地透過 Git 記錄快速釐清過往的邏輯與流程。

而對我們前端工程師來說，最重要的實作細節，其實我是不建議寫成文件的，因為跟程式碼相關的文件、註解，只要稍有疏忽就容易與實際狀況脫節，而這種脫節的文件某種角度上其實比沒有文件還糟糕。

所以我屬於主張透過 Type 與測試來作為實作程式碼的文件。

舉例來說，利用 TypeScript 可以把 function 的參數、回傳值定義清楚，搭配上正確的命名，可以讓程式碼本身就具備說明文件的能力，而且也因為 Type system 強化了 Editor 的能力，可以更容易清晰的看到 function、組件是如何被使用，以及在哪裡使用。

而需求 Spec 的實作，也可以透過單元測試、UI 組件測試等方式來保留下來，在上面提到的需求分析文件中，QA 會提供相關的測試用例，這些測試用例就可以在這邊發揮用處。

不但可以留下可供閱覽的訊息，也大幅避免了改 A 壞 B 的風險，讓未來的我們可以放心大膽的重構程式。

上面洋洋灑灑的一大段，應該也能看出來我覺得最需要撰寫的是哪種文件了吧？

不過我想一開始說要做需求分析、寫文件，應該很多人兩手一攤不知如何下手對吧！

文章的最後我就分享一個分析文件的檢查表，讓你有個參考、檢視的方向，當然你也可以再依照自己的需求去調整內容囉。