在軟件開發中，沒有什么比獲得一個幾乎沒有文檔并且需要維護它的代碼庫更具挑戰性的了。文檔不僅告訴工程師特定函數或變量的作用，而且還演示和傳達了軟件以特定方式實現的原因。在構建軟件時會做出數百萬個決策，對于嵌入式開發人員來說，盡可能多地保留該決策制定過程可能是至關重要的。

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

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

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

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

　　技巧 2 – 自動生成文檔

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

　　技巧 3 – 寫不明顯的評論

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

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

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

　　技巧 5 – 創建文檔標準

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

　　技巧 6 – 使用文檔模板

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

　　技巧 7 – 從圖表中拉/推

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

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

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

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

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

　　技巧 10 – 嵌入圖像和圖表

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