如何為開發專案編寫規範的README檔案（windows），此文詳解

詩筱涵發表於2020-11-25

為什麼要寫這篇部落格？

　　其實我是一個入坑已經半年的程式設計師，因為不是計算機專業，只能自己摸索，所以我深知部落格的重要性。每次我的學習筆記啊，專案的，面試題啊，有的，只要有時間，我肯定上傳上來，一方面自己可以隨時隨地的看，另一方面也可以方便大家。

　　瞭解一個專案，恐怕首先都是通過其Readme檔案瞭解資訊。如果你以為Readme檔案都是隨便寫寫的那你就錯了。github，oschina git gitcafe的程式碼託管平臺上的專案的Readme.MD檔案都是有其特有的語法的。稱之為Markdown語法，今天要寫的是關於README檔案在windows中如何寫，怎麼寫出來才符合要求，寫出來才好看，這樣就不得不說一下MarkDown編譯器了。

　　也許很多大神說，Markdown這麼簡單的，還需要寫個部落格炫耀？

　　其實你錯了，對於我們這些在windows上操作慣了的野路子，根本對除了word之外的編輯語言不感冒，也不習慣，但是每次專案都會需要README檔案，記得我第一次寫的README檔案是TXT格式，被老師嘲笑了，說README檔案是.md格式，但是我自己比較笨，請教了一個哥們，終於知道了寫README的好方法，那就是使用mardkdown工具，我下載的是有道雲筆記（我還用的是windows作業系統），他不但有MARKDOWN，更重要的是，還有MarkDown使用指南，（大家不要誤會，我不是推銷這個軟體，對於還是小白的我，覺得遇到了神器，很激動）。既然有這個了，那麼我的問題就迎刃而解了。

　　這篇文說到這裡，這才剛剛開始，下面主要介紹一下 MarkDown的主要用法，方便大家寫README檔案。

為什麼要寫README檔案？

　　對於這個問題詳解，請看部落格：http://www.cnblogs.com/wj-1314/p/7551184.html

　　這個問題很簡單，因為README的編寫，過了很長時間後，你仍然知道你當初寫了什麼；因為README的編寫，其他人看你的程式碼不需要那麼費勁；因為README的編寫，你程式碼的質量就大大的提高；因為README的編寫，你的語言水平就大大的提高了。

　　所以說README應該簡短，大家不要以為寫這個很麻煩，這個東西能夠節省你和別人的很多時間。

完整的README包括什麼內容？

　　關於README的內容，這是我覺得是每個專案中都應該有的一個檔案，目的是能簡要的描述該專案的資訊，讓讀者快速瞭解這個專案。

一，它需要說以下幾個事項：

1，軟體定位，軟體的基本功能

2，執行程式碼的方法：安裝環境，啟動命令等

3，簡要的使用說明

4，程式碼目錄結構說明，更詳細點可以說明軟體的基本原理

5，常見問題說明

二，它包括了一下內容：

專案和所有子模組和庫的名稱（對於新使用者，有時不同命名會導致混亂）

對所有專案，和所有子模組和庫的描述

如何使用 5-line code（如果是一個庫）

版權和許可資訊（或閱讀許可證）

抓取文件指令

安裝、配置和執行程式的指導

抓取最新程式碼和構建它們的說明（或快速概述和「閱讀 Install」）

作者列表或「Read AUTHORS」

提交bug，功能要求，提交補丁，加入郵件列表，得到通知，或加入使用者或開發開發區群的介紹

其他聯絡資訊（電子郵件地址，網站，公司名稱，地址等）

一個簡短的歷史記錄（更改，替換或者其他）

法律宣告

3，一個簡單的範本（當然，我們前期寫的話，不必要那麼麻煩，就寫幾個簡單的必要的東西，比如法律宣告啊，聯絡記錄啊等等，就不必要寫）

複製程式碼

DEMO
===========================

###########環境依賴
node v0.10.28+
redIs ~

###########部署步驟
1. 新增系統環境變數
    export $PORTAL_VERSION="production" // production, test, dev


2. npm install  //安裝node執行環境

3. gulp build   //前端編譯

4. 啟動兩個配置(已forever為例)
    eg: forever start app-service.js
        forever start logger-service.js


###########目錄結構描述
├── Readme.md                   // help
├── app                         // 應用
├── config                      // 配置
│   ├── default.json
│   ├── dev.json                // 開發環境
│   ├── experiment.json         // 實驗
│   ├── index.js                // 配置控制
│   ├── local.json              // 本地
│   ├── production.json         // 生產環境
│   └── test.json               // 測試環境
├── data
├── doc                         // 文件
├── environment
├── gulpfile.js
├── locales
├── logger-service.js           // 啟動日誌配置
├── node_modules
├── package.json
├── app-service.js              // 啟動應用配置
├── static                      // web靜態資源載入
│   └── initjson
│       └── config.js         // 提供給前端的配置
├── test
├── test-service.js
└── tools



###########V1.0.0 版本內容更新
1. 新功能     aaaaaaaaa
2. 新功能     bbbbbbbbb
3. 新功能     ccccccccc
4. 新功能     ddddddddd

複製程式碼