在嵌入式軟件開(kāi)發(fā)過(guò)程中，一般來(lái)說(shuō)，花在測(cè)試和花在編碼的時(shí)間比為3:1(實(shí)際上可能更多)。這個(gè)比例隨著你的編程和測(cè)試水平的提高而不斷下降，但不論怎樣，軟件測(cè)試對(duì)一般人來(lái)講很重要。

在軟件開(kāi)發(fā)中，沒(méi)有什么比獲得一個(gè)幾乎沒(méi)有文檔并且需要維護(hù)它的代碼庫(kù)更具挑戰(zhàn)性的了。文檔不僅告訴工程師特定函數(shù)或變量的作用，而且還演示和傳達(dá)了軟件以特定方式實(shí)現(xiàn)的原因。在構(gòu)建軟件時(shí)會(huì)做出數(shù)百萬(wàn)個(gè)決策，對(duì)于嵌入式開(kāi)發(fā)人員來(lái)說(shuō)，盡可能多地保留該決策制定過(guò)程可能是至關(guān)重要的。

記錄代碼的部分問(wèn)題歸結(jié)為交付壓力、不正確的設(shè)計(jì)以及記錄事物如何工作的事實(shí)并不像開(kāi)發(fā)它那樣有趣或令人興奮!許多工程師討厭編寫(xiě)代碼，但它是嵌入式工程師所做工作的重要組成部分，我們不能跳過(guò)它或三心二意地創(chuàng)建它。但是，在軟件開(kāi)發(fā)階段可以牢記一些技巧，以確保未來(lái)的開(kāi)發(fā)人員保持他們的發(fā)際線。

技巧 1 – 隨手記錄而不是事后記錄

交付產(chǎn)品的壓力通常會(huì)導(dǎo)致狂野風(fēng)格的編碼，其中代碼到處亂扔，只是為了讓某些東西正常工作，以便可以將其推出門(mén)外，在瘋狂的編碼過(guò)程中，很少考慮寫(xiě)下代碼實(shí)際在做什么。產(chǎn)品交付后，設(shè)計(jì)團(tuán)隊(duì)會(huì)在“文檔”階段回顧代碼。這樣做的問(wèn)題是，在編寫(xiě)代碼之后可能需要數(shù)周甚至數(shù)月!對(duì)于一些工程師來(lái)說(shuō)，記住他們昨天早餐吃了什么可能是一個(gè)挑戰(zhàn)，更不用說(shuō)兩周前的一段代碼做了什么了。結(jié)果是不準(zhǔn)確的文檔，后來(lái)導(dǎo)致誤解和錯(cuò)誤。

訣竅當(dāng)然是在做出決定時(shí)隨時(shí)記錄。帶有外部文檔的正式流程肯定會(huì)減慢開(kāi)發(fā)人員的速度，但在代碼庫(kù)中添加注釋確實(shí)不需要更多時(shí)間。開(kāi)發(fā)人員可以做的第一件事是寫(xiě)幾行注釋說(shuō)明代碼將要做什么。如果對(duì)實(shí)現(xiàn)進(jìn)行更改，嵌入式開(kāi)發(fā)人員可以立即更新評(píng)論。無(wú)論如何，在編寫(xiě)代碼時(shí)開(kāi)發(fā)注釋只能節(jié)省時(shí)間并提高清晰度，從而減少錯(cuò)誤并加快交付速度。

技巧 2 – 自動(dòng)生成文檔

盡管非常詳細(xì)地記錄了代碼，但始終需要生成任何人無(wú)需查看代碼即可看到的外部文檔。這通常會(huì)導(dǎo)致雙重文檔工作。值得慶幸的是，有一些工具可以讀取代碼注釋?zhuān)缓笊纱a的接口和其他文檔詳細(xì)信息!讓工程師不必重復(fù)做同樣的工作!比如Doxygen。在開(kāi)發(fā)人員編寫(xiě)代碼時(shí)，他們會(huì)以特定方式格式化注釋?zhuān)⑹褂盟麄兿Ｍ谕獠课臋n中提供的詳細(xì)信息。然后，他們可以運(yùn)行 doxygen 并生成準(zhǔn)確反映軟件中評(píng)論的 html、rtf 或 pdf 文檔。這樣做的好處是，如果你使你的評(píng)論保持最新，那么外部文檔也將如此!

技巧 3 – 寫(xiě)不明顯的評(píng)論

當(dāng)開(kāi)發(fā)人員記錄他們的代碼時(shí)，這很棒，但當(dāng)文檔只不過(guò)是變量或函數(shù)名稱(chēng)的重復(fù)時(shí)，則非常煩人。評(píng)論應(yīng)該是描述性的，并提供超出顯而易見(jiàn)的額外細(xì)節(jié)!提供盡可能多的信息，并且不要忘記提及相關(guān)和相關(guān)的變量或函數(shù)。開(kāi)發(fā)人員應(yīng)該能夠通過(guò)閱讀評(píng)論來(lái)了解軟件的行為方式。從下圖可以看到一個(gè)示例，其中記錄了一個(gè)簡(jiǎn)單的映射數(shù)組。

技巧 4 – 提供示例用法以提高清晰度

當(dāng)函數(shù)或變量注釋包含如何使用它們的示例時(shí)，它會(huì)非常有用。說(shuō)它應(yīng)該如何使用是一回事，但更應(yīng)該清楚地展示它是如何使用的。除了減少對(duì)象被錯(cuò)誤使用的機(jī)會(huì)外，這還可以提供更清晰的畫(huà)面。下圖顯示了如何記錄函數(shù)的示例，向嵌入式開(kāi)發(fā)人員展示應(yīng)該如何使用它以消除猜測(cè)工作并給出清晰的畫(huà)面。

技巧 5 – 創(chuàng)建文檔標(biāo)準(zhǔn)

就像編寫(xiě)代碼一樣，應(yīng)該有一個(gè)與代碼注釋和文檔開(kāi)發(fā)相關(guān)的標(biāo)準(zhǔn)，由于文檔標(biāo)準(zhǔn)中的項(xiàng)目幾乎沒(méi)有那么多，因此強(qiáng)烈建議將其匯總到編碼標(biāo)準(zhǔn)中，這是為了確保團(tuán)隊(duì)中的每個(gè)人都以相同的方式評(píng)論和記錄，以確保易于開(kāi)發(fā)，開(kāi)發(fā)人員應(yīng)該專(zhuān)注于手頭的問(wèn)題，而不是試圖瀏覽評(píng)論。

技巧 6 – 使用文檔模板

確保注釋遵循標(biāo)準(zhǔn)的最簡(jiǎn)單方法是為標(biāo)題、源和支持文檔創(chuàng)建模板。創(chuàng)建新模塊時(shí)，它是從模板創(chuàng)建的，然后添加相關(guān)信息，這將有助于確保文件信息塊、代碼段、函數(shù)和變量都以相同的格式注釋?zhuān)@種方法最好的部分是它還節(jié)省了大量時(shí)間，并且可以幫助減少將一個(gè)模塊復(fù)制為另一個(gè)模塊的假冒模板時(shí)的復(fù)制和粘貼錯(cuò)誤。

技巧 7 – 從圖表中拉/推

在項(xiàng)目的軟件實(shí)施階段開(kāi)始之前，應(yīng)該有一個(gè)軟件設(shè)計(jì)階段。這個(gè)設(shè)計(jì)階段無(wú)疑產(chǎn)生了許多漂亮的圖表，例如在實(shí)際實(shí)現(xiàn)過(guò)程中使用的流程圖和狀態(tài)機(jī)。雖然這些文檔充當(dāng)了軟件的路線圖，但在開(kāi)發(fā)和測(cè)試過(guò)程中總是存在偏差!不幸的是，這些變化很少會(huì)回到圖表中，結(jié)果是設(shè)計(jì)文檔和軟件不匹配!在實(shí)施和測(cè)試階段，嵌入式開(kāi)發(fā)人員可以將這些圖表放在手邊，以便如果出現(xiàn)偏差，可以在現(xiàn)場(chǎng)更新圖表，讓它們稍后更新永遠(yuǎn)不是正確的答案。畢竟，我們總是有最好的打算回去更新或修復(fù)某些東西，但從來(lái)沒(méi)有時(shí)間去做。

技巧 8 – 一致地使用注釋括號(hào)

聽(tīng)起來(lái)很奇怪，許多開(kāi)發(fā)人員已經(jīng)為何時(shí)、何地以及應(yīng)該使用何種類(lèi)型的注釋括號(hào)而進(jìn)行了戰(zhàn)斗!這一切都?xì)w結(jié)為一致性。如果一個(gè)團(tuán)隊(duì)決定只使用 /* ... */ 樣式的評(píng)論，那么就只使用那個(gè)樣式。如果 // 樣式已確定，則使用該樣式。無(wú)論偏好如何，請(qǐng)確保每次都以相同的方式完成，這將有助于讓生活更輕松一點(diǎn)。

技巧 9 – 保持可讀性(即格式良好)

保持代碼結(jié)構(gòu)化和易于閱讀非常重要，以確保誤解和錯(cuò)誤不會(huì)進(jìn)入代碼。評(píng)論也不例外。零星結(jié)構(gòu)的評(píng)論使眼睛很難捕捉到評(píng)論，更重要的是很難捕捉到不合適的東西。注釋的格式應(yīng)該是這樣的，如果代碼被打印出來(lái)，注釋不會(huì)跨多個(gè)頁(yè)面運(yùn)行。如果你使用塊指示符，則在文件頭或函數(shù)注釋等大塊注釋中，不要包含任何尾隨字符，例如 # 或 *，這只會(huì)使更新文檔更加困難。

技巧 10 – 嵌入圖像和圖表

通過(guò)使用自動(dòng)化工具，嵌入式開(kāi)發(fā)人員可以在構(gòu)建的文檔中包含編碼標(biāo)準(zhǔn)、縮寫(xiě)、項(xiàng)目詳細(xì)信息、要求和大量其他項(xiàng)目，甚至可以包括流程圖等設(shè)計(jì)圖!利用這種類(lèi)型的功能，代碼庫(kù)不僅可以包含已執(zhí)行的代碼和邏輯，還可以在一個(gè)地方包含你可能想了解的有關(guān)項(xiàng)目的任何內(nèi)容!