專家分享:注釋嵌入式軟件的十大技巧
技巧4——提供使用例子以便更清楚地了解用途
本文引用地址:http://butianyuan.cn/article/264705.htm函數(shù)或變量注釋中包含如何使用它們的例子是很有用的。說(shuō)應(yīng)該如何使用是一回事,但展示如何使用會(huì)讓人更清楚其用途。除了能夠減少錯(cuò)誤使用對(duì)象的機(jī)會(huì)外,還能給人一個(gè)更清晰的印象。圖2顯示了一個(gè)如何注釋函數(shù)的例子,它告訴開發(fā)人員應(yīng)該如何使用這個(gè)函數(shù),從而避免了容易出錯(cuò)的猜測(cè)過(guò)程,使人能夠更清晰地了解其用途。
圖2——使用例子。
技巧5——創(chuàng)建注釋標(biāo)準(zhǔn)
就像寫代碼一樣,為代碼開發(fā)注釋和文檔也應(yīng)該有個(gè)標(biāo)準(zhǔn)。由于注釋標(biāo)準(zhǔn)中不可能有許多條款,因此特別推薦向編寫代碼標(biāo)準(zhǔn)靠攏。也就是說(shuō)確保小組中的每個(gè)成員以相同的方式進(jìn)行注釋和歸檔,從而確保開發(fā)的易用性。開發(fā)人員應(yīng)該專注于解決手頭的設(shè)計(jì)問(wèn)題,而不是費(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è)試過(guò)程中總會(huì)出現(xiàn)偏差!遺憾的是,這些變化很少會(huì)返回到圖表中。結(jié)果是設(shè)計(jì)文檔和軟件的不匹配!在實(shí)現(xiàn)和測(cè)試階段將這些圖表放在手邊,以便發(fā)生上述偏差時(shí)這些圖表能及時(shí)得到更新。將這些圖表留到日后更新永遠(yuǎn)不是正確的做法。雖然我們總是有返回去更新或修復(fù)的良好愿望,但這永遠(yuǎn)不是合適的時(shí)機(jī)。
linux操作系統(tǒng)文章專題:linux操作系統(tǒng)詳解(linux不再難懂)
評(píng)論