如何編寫一個項目開發文檔

項目開發過程中為了增加程式的可讀性和程式的健壯性， 友善後期程式的調試和維護，是以需要在開發過程中統一技術規範，一般會在項目初期确定好相關文檔作為這一統一的規範。不同公司會對文檔做不同要求，劃不同的分類，但一般來說（或者拿自己的經驗說）大緻可以分為需求文檔、接口文檔、流程圖（可以單獨作為一份檔案可以作為附件附在文檔中）、變更檔案等。

一、需求文檔

在項目啟動之後，項目的目标已經明确了，那麼就要開始着手幹活了，但是在幹活之前，需要對整個項目分析透徹。那麼，如何對業務進行分析呢，看以下的建議。

首先，開發人員要有随意轉換身份的意識和能力。

A、明确産品功能

在分析業務時，站在使用者的角度上，思考要做的産品能實作什麼功能。把所有的功能點列出來！

B、分析某一功能點的流程

在羅列了所有的功能之後，需要站在開發者的角度分析每一個功能點，考慮從用戶端到背景操作資料庫的整個流程，可以從是什麼、為什麼、在哪、怎麼做、誰來做、做完如何回報、回報給誰、上傳到哪、伺服器用什麼資料庫、資料庫需要什麼表、表裡有什麼字段、每個字段的屬性及意義等等。比如，我要要做一個軟體中個人頭像上傳的功能，首先明确我做的是上傳功能；為什麼要上傳？因為個人資料需要頭像；怎麼做上傳？通過網絡I/O實作；這個功能在什麼位置？軟體有個個人中心子產品，個人中心裡有個個人資訊子子產品，在這個子產品裡可以上傳頭像；誰上傳？已經登入的使用者；上傳完之後如何回報？彈窗提示上傳成功；回報給誰？用戶端已登入的使用者；上傳到哪？伺服器上；用什麼資料庫？MySQL;需要什麼表？（存到）使用者表；表裡有什麼字段？使用者資訊的基本字段；每個字段的屬性及意義？略。在思考完這些問題之後，可以把一個功能點串成一條完整的從前端到資料庫的線。

C、整合各個功能點–明确分工

在串完所有的功能點之後，站在一個高一層次的角度，把每個功能點之間的聯系理清楚，按照互相的聯系分工合作，優化其中的細節問題。

D、撰寫需求文檔

分工完成之後，按照第二步分析的内容，每個人把自己負責的功能整理成文檔，最後合并文檔，作為統一的需求文檔。

E、繪制業務流程圖

需求文檔确定之後，繪制整個項目的業務流程圖，這時候的流程圖隻需要包含前端的業務流程，背景實作的流程圖不需要在需求文檔中展現，而是放在後面的接口文檔中。

二、接口文檔

不同公司對接口文檔的要求也不盡相同，但包括的内容卻是大同小異的。封面、标題、審批頁、修訂曆史以及格式字型等等風格迥異的次要内容不做贅述，隻講幹貨！幹貨！幹貨！

A、請求位址

需要哪個線上位址就寫哪個。注意不要反低級錯誤，比如寫錯某個字母或者大小寫問題。

B、接口資訊

說明請求方式，是POST還是GET。

C、功能描述

清晰地描述接口功能，要求言簡意赅，不要寫太多廢話，也不要遺漏任何細節。

D、接口參數說明

聲明參數的名稱，嚴格要求與調用一緻，包括大小寫；

簡單說明參數的含義；

參數的資料類型，是string 、int 還是long等（例如參數為@RequestParam(“appKey”)  String appKey,  @RequestParam(“randomId”)  Integer randomId）；

備注部分，說明參數值是需要哪個公司提供，并詳細說明參數怎麼生成的，例如時間戳，是哪個時間段的；參數是否必填，一些參數是必須要有的，有些是可選參數，一定要注意寫清晰。

E、傳回值說明

有一個模闆傳回值，并說明每個傳回參數的意義。提供一個真實的調用接口，真實的傳回值。

F、接口調用限制

為了安全，雙方采用一個一緻的加密算法，保證接口調用的安全。

G、文檔維護

文檔維護時，修改内容部分需要有修改人、修改日期、版本号的資訊。

三、流程圖

流程圖可以單獨作為一份檔案，也可以作為附件附在對應的文檔中，具體執行按要求來。

業務流程圖

程式結構圖

程式流程圖

四、變更檔案

在開發過程中如果出現與預期計劃、文檔不一緻的地方，則視為發生變更，此時大緻需要提供以下資訊：

A、版本曆史（版本号、基本資訊）

B、變更前現狀

C、變更内容

D、影響評估

E、審批

作者：Fuzz_

來源：CSDN

原文：https://blog.csdn.net/qq_36186690/article/details/82903265

版權聲明：本文為部落客原創文章，轉載請附上博文連結！