新聞中心

EEPW首頁 > 嵌入式系統(tǒng) > 牛人業(yè)話 > 專家分享:注釋嵌入式軟件的十大技巧

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

作者: 時(shí)間:2014-10-31 來源:網(wǎng)絡(luò) 收藏

  在軟件開發(fā)過程中沒有比獲得一個(gè)只有很少甚至沒有說明文檔的代碼庫而又要求進(jìn)行維護(hù)更具挑戰(zhàn)性的事情了。這些文檔不只是告訴工程師某個(gè)特定函數(shù)或變量是做什么的,而且能夠展示和傳達(dá)軟件為何以某個(gè)特定方式實(shí)現(xiàn)。在軟件實(shí)現(xiàn)過程中會(huì)作出成千上萬個(gè)決策,因此維護(hù)工程師甚至未來的你盡可能多地保留這些決策過程至關(guān)重要。

本文引用地址:http://butianyuan.cn/article/264705.htm

  代碼的問題部分原因來自出貨壓力、不正確的設(shè)計(jì)以及代碼是如何工作的事情沒有開發(fā)來得有趣或興奮這個(gè)事實(shí)!許多工程師(包括我自己)憎恨必須代碼,但這項(xiàng)工作在工程師開發(fā)過程中是如此重要,以致于我們絕對(duì)不能省略或三意二意地去做。然而,可以在軟件開發(fā)過程中記住一些技巧,它們有助于確保未來開發(fā)人員維護(hù)好代碼開發(fā)中的任何細(xì)微變動(dòng)。

  技巧1——隨時(shí)而不是過后進(jìn)行注釋

  交付產(chǎn)品的壓力經(jīng)常導(dǎo)致天馬行空般的編碼風(fēng)格,為了完成任務(wù)以便盡早推出產(chǎn)品,代碼是想到哪就編到哪。在瘋狂的代碼編寫過程中,很少想到記錄下代碼要完成的功能。等產(chǎn)品交貨后,設(shè)計(jì)人員才會(huì)回去瀏覽代碼并進(jìn)行“注釋”。這樣做的問題是,這時(shí)已經(jīng)距離寫完代碼幾周甚至幾個(gè)月的時(shí)間了!對(duì)一些工程師來說記起昨天早餐吃的是什么都很難,更不用說兩周前寫的一段代碼了。最終結(jié)果是不準(zhǔn)確的注釋說明,日后往往會(huì)引起誤解和缺陷。

  這里的技巧當(dāng)然是在進(jìn)行決策的同時(shí)隨時(shí)進(jìn)行注釋。形式化的外部文檔注釋過程無疑會(huì)降低開發(fā)人員的進(jìn)度,但向代碼庫中增加注釋真的不會(huì)占用更多時(shí)間。開發(fā)人員能夠做的第一件事是先對(duì)代碼要做什么事寫一些注釋行,然后再寫代碼。如果實(shí)現(xiàn)發(fā)生了變化,開發(fā)人員可以立即更新注釋。在任何情況下,在編寫代碼的同時(shí)寫下注釋只會(huì)節(jié)省時(shí)間和增加條理性,從而更少發(fā)生錯(cuò)誤,產(chǎn)品也能更快的上市。

  技巧2——自動(dòng)生成注釋文檔

  盡管對(duì)代碼做了很詳細(xì)的注釋,但總是有生成外部文檔的要求,以便任何人不看代碼就能明白程序功能。這個(gè)要求經(jīng)常導(dǎo)致雙倍的注釋工作量。幸運(yùn)的是,市場(chǎng)上有現(xiàn)成的工具可以自動(dòng)讀取代碼注釋、然后生成界面和代碼的其它文檔細(xì)節(jié)!幫助工程師避免必須做兩次相同的工作!一個(gè)具有這種功能的免費(fèi)工具例子是。當(dāng)開發(fā)人員在編寫他們的代碼時(shí),他們以指定方式格式化他們的注釋,并提供他們想要在外部文檔中展示的細(xì)節(jié)內(nèi)容。然后他們就可以運(yùn)行生成真實(shí)反映軟件內(nèi)注釋的html、rtf或pdf文檔。美妙的是如果你更新注釋,外部文檔也會(huì)自動(dòng)更新!

  技巧3——不要寫顯式的注釋

  雖然開發(fā)人員寫了代碼注釋,但如果注釋只是變量或函數(shù)名字的重復(fù),會(huì)特別令人惱火。注釋應(yīng)該是描述性的文字,需要提供顯式意思之外更多的細(xì)節(jié)!提供盡可能多的信息,而且不要忘了提及相關(guān)和關(guān)聯(lián)的變量或函數(shù)。開發(fā)人員應(yīng)該能夠只通過閱讀注釋就了解軟件的行為。圖1給出了一個(gè)注釋簡單映射數(shù)組代碼的例子。

  

注釋嵌入式軟件的十大技巧

 

  圖1:映射數(shù)組。

linux操作系統(tǒng)文章專題:linux操作系統(tǒng)詳解(linux不再難懂)

上一頁 1 2 3 下一頁

關(guān)鍵詞: 嵌入式 注釋 Doxygen

評(píng)論


相關(guān)推薦

技術(shù)專區(qū)

關(guān)閉