專(zhuān)家分享：注釋嵌入式軟件的十大技巧

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

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

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

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

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

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

　　盡管對代碼做了很詳細的注釋?zhuān)偸怯猩赏獠课臋n的要求，以便任何人不看代碼就能明白程序功能。這個(gè)要求經(jīng)常導致雙倍的注釋工作量。幸運的是，市場(chǎng)上有現成的工具可以自動(dòng)讀取代碼注釋、然后生成界面和代碼的其它文檔細節!幫助工程師避免必須做兩次相同的工作!一個(gè)具有這種功能的免費工具例子是Doxygen。當開(kāi)發(fā)人員在編寫(xiě)他們的代碼時(shí)，他們以指定方式格式化他們的注釋?zhuān)⑻峁┧麄兿胍谕獠课臋n中展示的細節內容。然后他們就可以運行Doxygen生成真實(shí)反映軟件內注釋的html、rtf或pdf文檔。美妙的是如果你更新注釋?zhuān)獠课臋n也會(huì )自動(dòng)更新!

　　技巧3——不要寫(xiě)顯式的注釋

　　雖然開(kāi)發(fā)人員寫(xiě)了代碼注釋?zhuān)绻⑨屩皇亲兞炕蚝瘮得值闹貜?，?huì )特別令人惱火。注釋?xiě)撌敲枋鲂缘奈淖?，需要提供顯式意思之外更多的細節!提供盡可能多的信息，而且不要忘了提及相關(guān)和關(guān)聯(lián)的變量或函數。開(kāi)發(fā)人員應該能夠只通過(guò)閱讀注釋就了解軟件的行為。圖1給出了一個(gè)注釋簡(jiǎn)單映射數組代碼的例子。

　　圖1：映射數組。