如何爲開發項目編寫規範的README文件（windows），此文詳解

時間 2020-07-09

標籤如何開發項目編寫規範 readme 文件 windows 此文詳解欄目 Windows 简体版

原文原文鏈接

爲何要寫這篇博客？

　　其實我是一個入坑已經半年的程序員，由於不是計算機專業，只能本身摸索，因此我深知博客的重要性。每次個人學習筆記啊，項目的，面試題啊，有的，只要有時間，我確定上傳上來，一方面本身能夠隨時隨地的看，另外一方面也能夠方便你們。html

　　瞭解一個項目，恐怕首先都是經過其Readme文件瞭解信息。若是你覺得Readme文件都是隨便寫寫的那你就錯了。github，oschina git gitcafe的代碼託管平臺上的項目的Readme.MD文件都是有其特有的語法的。稱之爲Markdown語法，今天要寫的是關於README文件在windows中如何寫，怎麼寫出來才符合要求，寫出來纔好看，這樣就不得不說一下MarkDown編譯器了。前端

　　也許不少大神說，Markdown這麼簡單的，還須要寫個博客炫耀？node

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

　　這篇文說到這裏，這纔剛剛開始，下面主要介紹一下 MarkDown的主要用法，方便你們寫README文件。git

爲何要寫README文件？

　　對於這個問題詳解，請看博客：http://www.cnblogs.com/wj-1314/p/7551184.html程序員

　　這個問題很簡單，由於README的編寫，過了很長時間後，你仍然知道你當初寫了什麼；由於README的編寫，其餘人看你的代碼不須要那麼費勁；由於README的編寫，你代碼的質量就大大的提升；由於README的編寫，你的語言水平就大大的提升了。github

　　因此說README應該簡短，你們不要覺得寫這個很麻煩，這個東西可以節省你和別人的不少時間。web

完整的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