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

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

　　圖2——使用例子。

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

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

　　技巧6——使用文檔模板

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

　　技巧7——圖表的作用

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