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

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

　　圖2——使用例子。

　　技巧5——創(chuàng)建注釋標(biāo)準(zhǔn)

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

　　技巧6——使用文檔模板

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

　　技巧7——圖表的作用

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