如何寫一個通用的README規範

背景

咱們日常在進行項目開發時，通常都會把代碼上傳至代碼託管平臺上方便管理和維護。目前你們使用的託管平臺最多的仍是Github，國內外還有一些比較知名的代碼託管平臺，好比Gitlab、BitBucket，碼雲和碼市等。

但咱們在多人合做開發下，常常碰到的最頭疼的問題是，其餘開發者在交接給咱們一個項目時只是對項目目前現有的功能簡單的描述了下，咱們在後續迭代功能時忽然發現連最基本的項目如何運行都沒有給咱們交代，當時心中一萬隻那個什麼馬奔騰而過，只能去查看package.json的scripts，本身意會了。

那麼問題來了，咱們在交接一個項目時，如何保證項目能快速完整地交付給基友，今後過上無憂無慮的生活呢？答案是咱們只須要甩給他一份標準規範的README。

---

規範的README須要哪些內容

咱們經過一張截圖一塊兒來看看一份簡單的README規範都有哪些內容：

上面的readme規範模板在咱們feflow的README規範裏能夠看到

---

那麼咱們一塊兒來探討下，一份規範完整的README規範都應該有哪些內容呢？

1. 項目描述
2. 如何運行
3. 業務介紹
4. 項目備註
複製代碼

每一項都有哪些做用？

• 項目描述

  須要說明咱們的項目名，項目功能簡述，代碼倉庫地址，以及該項目的第一負責人。誰交接給咱們的項目，誰就是該項目的第一負責人。

• 如何運行

  1. 開發環境配置。通常是咱們須要的一些運行環境配置。
  2. 開發&發佈 命令。咱們怎麼經過命令開啓本地開發，以及構建發佈。
  3. 代理配置。若是咱們的項目在本地開發時須要用到一些代理工具，例如fiddler或whistle等，咱們須要列出代理的配置項。最好是直接導出一個代理配置的文件，放在項目下
  4. 發佈。若是咱們有用到一些發佈平臺，最好貼上項目的發佈模塊和發佈單，減小咱們發佈的時間成本。
  5. 錯誤告警及監控。相信咱們日常都會對線上的項目部署錯誤告警和監控日誌的服務，方便咱們及時排查現網問題，這裏咱們能夠加入項目的一些監控屬性ID
  6. 接口API。這裏咱們須要貼入項目中拉去的後臺接口地址以及描述，還有咱們的接口負責人，當後臺服務異常，能夠直接聯繫到後臺同窗。
  7. 數據上報。咱們在日常項目裏都有加入一些數據上報，給產品同窗統計業務數據用，這裏咱們最好闡述下都有哪些數據的上報。若是上報出問題，產品妹子找過來，咱們不至因而一臉懵逼。

• 業務介紹

  對於前端來講，咱們一個項目可能不止一個頁面，那麼咱們須要給出如下信息:

  1. 業務入口地址及渠道連接 即咱們整個項目的入口頁面，或者比較重要的頁面地址。通常入口頁面，咱們可能會在多個渠道進行投放，那麼須要列出全部的渠道連接

  2. 各頁面及描述 列出咱們項目內的全部頁面信息，好比下面這樣：

     頁面目錄	頁面描述	頁面連接	參數描述
     index	首頁	now.qq.com	無

• 項目備註 項目中須要告訴其餘開發者一些關鍵信息，好比咱們頁面打包構建，須要注意哪些問題等等，這些信息雖然不是必須的，可是能夠幫助其餘開發者下降開發的風險成本。

最後

上面是咱們一個規範的README所需的一些信息和內容，加粗內容是我認爲README裏的一些必需信息，你們也能夠在此基礎上針對本身項目實際的開發場景來擴展一些規範信息。

---

《IVWEB 技術週刊》 震撼上線了，關注公衆號：IVWEB社區，每週定時推送優質文章。

• 週刊文章集合: weekly
• 團隊開源項目: Feflow