嵌入式開發(fā)不用寫文檔？

最近看到有交流群在討論：嵌入式開發(fā)到底要不要寫文檔的話題。

這個(gè)話題要展開討論的話，可能要分很多種情況，公司規(guī)模、項(xiàng)目難度、管理制度。。。

分享正文之前，給大家推薦一些嵌入式相關(guān)的職位：

俗話說(shuō)，不會(huì)寫文檔的工程師不是好的工程師！

如果你只會(huì)寫代碼，而從不寫文檔，你可能只適合中午寫代碼，因?yàn)樵缤頃?huì)“出事”。

不寫文檔有什么后果？

如果不寫文檔，開發(fā)過(guò)程中就會(huì)出現(xiàn)類似下面這些情況。

領(lǐng)導(dǎo)：這個(gè)功能不好、再添加一個(gè)功能、把這個(gè)功能去掉等。

軟件：這個(gè)功能不能實(shí)現(xiàn)、代碼只能重構(gòu)、一個(gè)bug引發(fā)N個(gè)bug等。

硬件：添加功能只能重新畫板、沒(méi)有考慮要預(yù)留通信接口等。

通常，在小公司不寫設(shè)計(jì)文檔很正常，但是隱患很大。反復(fù)增刪功能、調(diào)整方案這都需要付出大量時(shí)間和精力。

只是一兩次小改動(dòng)都還好，如果多次、大改動(dòng)的話，就會(huì)出現(xiàn)互相甩鍋、同事不和的后果。

不要問(wèn)為什么，經(jīng)歷過(guò)的人都懂

嵌入式項(xiàng)目，需要哪些設(shè)計(jì)文檔？

我之前參與開發(fā)的項(xiàng)目，從需求、設(shè)計(jì)、實(shí)現(xiàn)、測(cè)試、總結(jié)等這幾個(gè)階段下來(lái)，設(shè)計(jì)文檔多的時(shí)候有上100個(gè)文檔。

當(dāng)然，這里面是包含不同崗位（軟件、硬件、機(jī)械、測(cè)試等）、不同模塊等細(xì)分的各種文檔。

對(duì)于不同的項(xiàng)目，可能設(shè)計(jì)文檔種類和數(shù)量不同，比如你一個(gè)簡(jiǎn)單的電子手表，可只需要一個(gè)需求文檔、一個(gè)方案設(shè)計(jì)文檔就可以了。

其實(shí)，項(xiàng)目越復(fù)雜，設(shè)計(jì)文檔越多。比如京東的倉(cāng)儲(chǔ)物流這一套系統(tǒng)，你能想想一下有多少個(gè)設(shè)計(jì)文檔嗎？光是需求階段的文檔肯定都有上百個(gè)：需求、評(píng)估、審核等各種文檔。

當(dāng)然，對(duì)于我們普通的項(xiàng)目，需要的設(shè)計(jì)文檔可能幾個(gè) ~ 十幾個(gè)就可以了，

比如：需求文檔、評(píng)估文檔、總方案文檔、模塊方案文檔、通信協(xié)議文檔、測(cè)試用例文檔等。

每一種文檔沒(méi)有固定的格式，只需要結(jié)合你自己實(shí)際項(xiàng)目，把重點(diǎn)描述清楚，能指導(dǎo)開發(fā)人員，方便開發(fā)和設(shè)計(jì)即可。

舉例：xxx項(xiàng)目電源管理方案

下面分享一個(gè)簡(jiǎn)單方案設(shè)計(jì)文檔。

1.封面總體

就像一個(gè)本書的封面，把主要信息羅列出來(lái)。比如：

項(xiàng)目名稱、文檔版本、日期、作者、密級(jí)等。

比如：

2.文檔目錄

作為一個(gè)技術(shù)開發(fā)人員，如果你連word的目錄都不知道怎么生成，你應(yīng)該好好反思一下了。

目錄很簡(jiǎn)單，比如：

這里想說(shuō)下，目錄是自動(dòng)生成，而不是手動(dòng)編輯的目錄。

我就發(fā)現(xiàn)有人的目錄居然是手動(dòng)編輯的，不知道大家是不也這么“水”？

3.引言

這里引言也可以是“概述”，把整個(gè)方案的主要內(nèi)容進(jìn)行描述，比如這里簡(jiǎn)單列幾點(diǎn)：

4.框架

框架就是首先給人第一眼就能了解你這個(gè)項(xiàng)目有些什么東西。

比如系統(tǒng)框架、軟、硬件框架等。這里需要用到一些設(shè)計(jì)框架的工具，比如：Visio.

比如：

5.硬件設(shè)計(jì)

羅列硬件相關(guān)的設(shè)計(jì)信息，比如硬件供電、狀態(tài)等。

6.軟件流程

牽涉到軟件，在方案中必不可少的一點(diǎn)，就是軟件流程。

如果你軟件流程都不清楚，在開發(fā)過(guò)程中，肯定會(huì)反反復(fù)復(fù)修改代碼，甚至修改了數(shù)十版不能用。

軟件流程網(wǎng)上有很多例子可參看，比如按鍵檢測(cè)流程：

比如電壓、電流檢測(cè)流程：

7.系統(tǒng)狀態(tài)

每一個(gè)系統(tǒng)基本都由多個(gè)狀態(tài)（或者模式），比如工作狀態(tài)、空閑狀態(tài)、故障狀態(tài)等。

你要把系統(tǒng)可能遇到的狀態(tài)都列出來(lái)，并描述清楚。比如：

8.通信協(xié)議、接口設(shè)計(jì)等其他

比如你的項(xiàng)目中會(huì)用到通信，需要把通信協(xié)議整理出來(lái)。

或者簡(jiǎn)單描述通信相關(guān)的內(nèi)容，比如硬件使用了UART、CAN，通信協(xié)議使用CANopen、Modbus等。然后具體協(xié)議指令單獨(dú)一個(gè)文檔。（見：協(xié)議文檔）。

最后，以上內(nèi)容僅供參考，不同項(xiàng)目的情況不同。根據(jù)項(xiàng)目情況把設(shè)計(jì)中需要考慮的重要信息整理出來(lái)，并容易理解就可以了。

審核編輯 ：李倩