在軟體開發過程中沒有比獲得一個只有很少甚至沒有說明文件的程式碼庫而又要求進行維護更具挑戰性的事情了。這些文件不只是告訴工程師某個特定函式或變數是做什麼的，而且能夠展示和傳達軟體為何以某個特定方式實現。在軟體實現過程中會作出成千上萬個決策，因此維護工程師甚至未來的你儘可能多地保留這些決策過程至關重要。
註釋程式碼的問題部分原因來自出貨壓力、不正確的設計以及註釋程式碼是如何工作的事情沒有開發來得有趣或興奮這個事實!許多工程師(包括我自己)憎恨必須註釋程式碼，但這項工作在嵌入式工程師開發過程中是如此重要，以致於我們絕對不能省略或三意二意地去做。然而，可以在軟體開發過程中記住一些技巧，它們有助於確保未來開發人員維護好程式碼開發中的任何細微變動。
技巧1——隨時而不是過後進行註釋
交付產品的壓力經常導致天馬行空般的編碼風格，為了完成任務以便儘早推出產品，程式碼是想到哪就編到哪。在瘋狂的程式碼編寫過程中，很少想到記錄下程式碼要完成的功能。等產品交貨後，設計人員才會回去瀏覽程式碼並進行“註釋”。這樣做的問題是，這時已經距離寫完程式碼幾周甚至幾個月的時間了!對一些工程師來說記起昨天早餐吃的是什麼都很難，更不用說兩週前寫的一段程式碼了。最終結果是不準確的註釋說明，日後往往會引起誤解和缺陷。
這裡的技巧當然是在進行決策的同時隨時進行註釋。形式化的外部文件註釋過程無疑會降低開發人員的進度，但向程式碼庫中增加註釋真的不會佔用更多時間。開發人員能夠做的第一件事是先對程式碼要做什麼事寫一些註釋行，然後再寫程式碼。如果實現發生了變化，開發人員可以立即更新註釋。在任何情況下，在編寫程式碼的同時寫下注釋只會節省時間和增加條理性，從而更少發生錯誤，產品也能更快的上市。
技巧2——自動生成註釋文件
儘管對程式碼做了很詳細的註釋，但總是有生成外部文件的要求，以便任何人不看程式碼就能明白程式功能。這個要求經常導致雙倍的註釋工作量。幸運的是，市場上有現成的工具可以自動讀取程式碼註釋、然後生成介面和程式碼的其它文件細節!幫助工程師避免必須做兩次相同的工作!一個具有這種功能的免費工具例子是Doxygen。當開發人員在編寫他們的程式碼時，他們以指定方式格式化他們的註釋，並提供他們想要在外部文件中展示的細節內容。然後他們就可以執行Doxygen生成真實反映軟體內註釋的html、rtf或pdf文件。美妙的是如果你更新註釋，外部文件也會自動更新!
技巧3——不要寫顯式的註釋
雖然開發人員寫了程式碼註釋，但如果註釋只是變數或函式名字的重複，會特別令人惱火。註釋應該是描述性的文字，需要提供顯式意思之外更多的細節!提供儘可能多的資訊，而且不要忘了提及相關和關聯的變數或函式。開發人員應該能夠只通過閱讀註釋就瞭解軟體的行為。圖1給出了一個註釋簡單對映陣列程式碼的例子。
技巧4——提供使用例子以便更清楚地瞭解用途
函式或變數註釋中包含如何使用它們的例子是很有用的。說應該如何使用是一回事，但展示如何使用會讓人更清楚其用途。除了能夠減少錯誤使用物件的機會外，還能給人一個更清晰的印象。圖2顯示了一個如何註釋函式的例子，它告訴開發人員應該如何使用這個函式，從而避免了容易出錯的猜測過程，使人能夠更清晰地瞭解其用途。
技巧5——建立註釋標準
就像寫程式碼一樣，為程式碼開發註釋和文件也應該有個標準。由於註釋標準中不可能有許多條款，因此特別推薦向編寫程式碼標準靠攏。也就是說確保小組中的每個成員以相同的方式進行註釋和歸檔，從而確保開發的易用性。開發人員應該專注於解決手頭的設計問題，而不是費勁地去搞懂註釋。
技巧6——使用文件模板
確保註釋遵循標準的最容易的方法是為標頭檔案、原始檔和支援檔案建立模板。當建立一個新模組時，可以從模板入手，然後增加相關的資訊。這將有助於確保檔案資訊塊、程式碼段、函式和變數都用相同的格式註釋。這種方法的最大優勢是能夠節省大量時間，並有助於減少將一個模組拷貝到另一個偽模板時發生的`拷貝貼上錯誤。為了讓生活更加輕鬆，我特意開發了可以用於定義標頭檔案和原始檔的模板。
技巧7——圖表的作用
在一個專案的軟體實現階段開始之前，應該有一個軟體設計階段。這個設計階段無疑會生成許多漂亮的圖(如流程圖和狀態機)，並被用於實際實現。雖然這些文件作為軟體的開發路線圖，但在開發和測試過程中總會出現偏差!遺憾的是，這些變化很少會返回到圖表中。結果是設計文件和軟體的不匹配!在實現和測試階段將這些圖表放在手邊，以便發生上述偏差時這些圖表能及時得到更新。將這些圖表留到日後更新永遠不是正確的做法。雖然我們總是有返回去更新或修復的良好願望，但這永遠不是合適的時機。
技巧8——保持註釋框使用的一致性
就像聽起來一樣奇怪，許多網路爭論的內容是何時、哪裡使用何種型別的註釋框!不過嚴肅地講，不管你的信仰是什麼，歸根到底是一致性問題。如果一個團隊決定只使用/*…*/型別的註釋，那麼就只使用這種型別。如果決定使用//型別，那就只使用//型別。作者個人的觀點是傾向於使用/*…*/進行函式和模組級說明，使用//進行函式程式碼說明。不管選擇是什麼，確保每次都按同樣的方式去做，這樣有助於生活更加輕鬆。
技巧9——使註釋更容易閱讀(即格式的美化)
為了確保避免誤解並由此產生程式碼缺陷，使程式碼保持結構化和容易閱讀很重要。註釋也一樣。偶爾結構化的註釋會使眼睛很難捕捉註釋，更難捕捉不在合適位置的內容。應該對註釋進行格式化處理，這樣如果程式碼打印出來時(雖然現在不常列印，但我偶然仍會列印程式碼)註釋就不會分到好幾頁上去。在大塊註釋(如檔案頭或函式註釋)中，如果你使用塊指示器，千萬不要包含進任何拖尾字元(如#或*)，要不只會使文件更新變得更加困難。
技巧10——嵌入影象和圖表
藉助自動化工具的使用，在註釋文件中包含編碼標準、縮寫詞、專案細節、要求和大量其它條款就成了可能。甚至能夠包含諸如流程圖等設計性圖表!使用這類功能允許程式碼庫不僅包含執行程式碼和邏輯，還包含你想要了解的專案所有內容，並且所有資訊都放在同一個地方。
