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

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

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

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

　　技巧 2 – 自動生成文檔

　　盡管非常詳細地記錄了代碼，但始終需要生成任何人無需查看代碼即可看到的外部文檔。這通常會導致雙重文檔工作。值得慶幸的是，有一些工具可以讀取代碼注釋，然后生成代碼的接口和其他文檔詳細信息!讓工程師不必重復做同樣的工作!比如Doxygen。在開發(fā)人員編寫代碼時，他們會以特定方式格式化注釋，并使用他們希望在外部文檔中提供的詳細信息。然后，他們可以運行
doxygen 并生成準確反映軟件中評論的 html、rtf 或 pdf
文檔。這樣做的好處是，如果你使你的評論保持最新，那么外部文檔也將如此!

　　技巧 3 – 寫不明顯的評論

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

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

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

　　技巧 5 – 創(chuàng)建文檔標準

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

　　技巧 6 – 使用文檔模板

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

　　技巧 7 – 從圖表中拉/推

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

　　技巧 8 – 一致地使用注釋括號

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

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

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

　　技巧 10 – 嵌入圖像和圖表

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