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

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

　　圖2——使用例子。

　　技巧5——創建注釋標準

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

　　技巧6——使用文檔模板

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

　　技巧7——圖表的作用

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