你的git項目須要一個高質量的README

不管在公司內部，仍是在開源社區，咱們在接觸一個新項目的時候，基本上都會先去看README.一份好的README可使你快速瞭解甚至上手這個項目，然而一份糟糕的README可能會讓你崩潰。

README就像是一本供開發者閱讀的程序簡介書。爲了寫好這本書，給別人或者本身提升效率，咱們須要學習一些技巧來編寫高可讀性的README.

什麼是README

README（顧名思義——"讀我"）是開始一個新項目的時候首先須要閱讀的文件。它是關於項目有用信息的集合，一樣也是一本手冊。

egg的README

一份好的README的益處

對於使用你項目的人而言，一份好的REAME可讓其餘人迅速瞭解咱們的代碼包含的內容、重點、使用方法、技術棧、疑難雜症等。這毫無疑問能夠大大減小溝通成本。若是你不想不厭其煩地回答新人的各類問題，那就寫一份完整且高可讀性的README吧。

而對於咱們自身而言，README不只可讓你在久別重逢該項目後找到往日的熟悉感，它也能夠幫助咱們總結和規劃。咱們能夠將解決問題的靈感來源記錄（如stackoverflow連接），也能夠添上完成的功能和即將要實現的特性和優化。從這個角度來講，它像是一本關於項目的日記或者藍圖。

使用何種語言

若是是開源項目，我建議使用英語。畢竟我們要有一顆international的心。若是是公司內部項目，仍是中文「可讀性"更強.

README應該包括的內容

首先至少應該包括的內容有:

• 標題(Title)
• 介紹(Introduction)
• 技術棧(Technologies)
• 啓動(Launch or Setup)

若是考慮得更完善一些還包括：

• 目錄(Table of contents)
• 功能特性(Features)
• 代碼示例(Code Examples)
• 項目狀態（Status）
• 來源(Sources)
• 外部連接(Links)
• 聯繫(Contact)
• 其它信息
• ...

固然關於內容規範問題仁者見仁智者見智，只要可以達到README應該有的效果，就是好的實踐。

標題(title)

一個標題應該很清晰地表達這是一個什麼項目。一般來講，它會是項目名稱。

介紹(introduction)

介紹應該短小精悍，二、3句話就能夠講明白這個項目的目的以及解決的問題。

技術棧(Technologies)

這是程序員最關心的部分之一。它們是這個項目的地基，有了完整且正確的它們才能構建出整個項目，而不是一啓動就無數報錯。因此咱們理應把項目的語言、依賴和對應的版本寫下來。好比:

• Java 8
• Spring Boot 2.x
• easyexcel 1.1.0

啓動(Launch or Setup)

如何運行也是開發者十分關心的部分。咱們不能僅僅只寫下一行啓動命令，好比npm run start，一般來講咱們還須要告訴使用者如何安裝依賴、如何修改配置甚至初始化數據庫。你寫得越詳細，別人就越少吐槽。

目錄(Table of contents)

在篇幅較長、內容較多的狀況下，目錄提供了一個各部份內容的快捷入口，而不是無止盡地滑滾輪。咱們能夠用markdown提供的便捷語法，建立一個簡單的目錄。

功能特性(Features)

經過閱讀這部分，人們將迅速瞭解該項目所支持的功能和特性。另外咱們也應當將TODO List寫上去，以供本身規劃項目和他人瞭解它的將來發展方向。

代碼示例(Code Examples)

這對一些工具或者庫依賴項目來講是十分重要的。由於一般來講人們更願意直接複製粘貼來測試他們須要的效果。

項目狀態（Status）

項目處於開發階段仍是已經完成，是已經中止維護仍是遷移到了新的項目？這值得告訴讀者。

來源(Sources)

咱們在開發某項功能，或者解決某個bug的過程當中，有的時候會查閱一些文檔、教程或者從技術論壇尋找現成的解決方案（好比stackoverflow、掘金等）。將其中你認爲對本身或他人有價值的一部分記錄在案，寫下它們的描述和連接。我認爲在將來某個時間點，它可能會幫助到你或者別人。

外部連接(Links)

對於公司內部項目而言，可能會有項目管理平臺地址（如tapd）、接口文檔地址； 對於開源項目也可能有對應的完整文檔、教程、博客等。

聯繫(Contact)

主要是記錄做者本人或者開發團隊的聯繫方式。

總結

上述都只是我的見解和建議，只要適合本身的項目，可讀性高，達到減小溝通成本的目的就是好的README。

文章靈感來源：www.flynerd.pl/2018/06/jak…