專家分享：注釋嵌入式軟件的十大技巧

　　技巧4——提供使用例子以便更清楚地了解用途

　　函數或變量注釋中包含如何使用它們的例子是很有用的。說應該如何使用是一回事，但展示如何使用會讓人更清楚其用途。除了能夠減少錯誤使用對象的機會外，還能給人一個更清晰的印象。圖2顯示了一個如何注釋函數的例子，它告訴開發(fā)人員應該如何使用這個函數，從而避免了容易出錯的猜測過程，使人能夠更清晰地了解其用途。

　　圖2——使用例子。

　　技巧5——創(chuàng)建注釋標準

　　就像寫代碼一樣，為代碼開發(fā)注釋和文檔也應該有個標準。由于注釋標準中不可能有許多條款，因此特別推薦向編寫代碼標準靠攏。也就是說確保小組中的每個成員以相同的方式進行注釋和歸檔，從而確保開發(fā)的易用性。開發(fā)人員應該專注于解決手頭的設計問題，而不是費勁地去搞懂注釋。

　　技巧6——使用文檔模板

　　確保注釋遵循標準的最容易的方法是為頭文件、源文件和支持文件創(chuàng)建模板。當創(chuàng)建一個新模塊時，可以從模板入手，然后增加相關的信息。這將有助于確保文件信息塊、代碼段、函數和變量都用相同的格式注釋。這種方法的最大優(yōu)勢是能夠節(jié)省大量時間，并有助于減少將一個模塊拷貝到另一個偽模板時發(fā)生的拷貝粘貼錯誤。為了讓生活更加輕松，我特意開發(fā)了可以用于定義頭文件和源文件的模板。

　　技巧7——圖表的作用

　　在一個項目的軟件實現階段開始之前，應該有一個軟件設計階段。這個設計階段無疑會生成許多漂亮的圖(如流程圖和狀態(tài)機)，并被用于實際實現。雖然這些文檔作為軟件的開發(fā)路線圖，但在開發(fā)和測試過程中總會出現偏差!遺憾的是，這些變化很少會返回到圖表中。結果是設計文檔和軟件的不匹配!在實現和測試階段將這些圖表放在手邊，以便發(fā)生上述偏差時這些圖表能及時得到更新。將這些圖表留到日后更新永遠不是正確的做法。雖然我們總是有返回去更新或修復的良好愿望，但這永遠不是合適的時機。