在軟件實現(xiàn)過程中會作出成千上萬個決策，因此維護工程師甚至未來的你盡可能多地保留這些決策過程至關(guān)重要。

注釋代碼的問題部分原因來自出貨壓力、不正確的設(shè)計以及注釋代碼是如何工作的事情沒有開發(fā)來得有趣或興奮這個事實！

許多工程師（包括我自己）憎恨必須注釋代碼，但這項工作在嵌入式工程師開發(fā)過程中是如此重要，以致于我們絕對不能省略或三意二意地去做。

然而，可以在軟件開發(fā)過程中記住一些技巧，它們有助于確保未來開發(fā)人員維護好代碼開發(fā)中的任何細微變動。

技巧1——隨時而不是過后進行注釋

交付產(chǎn)品的壓力經(jīng)常導(dǎo)致天馬行空般的編碼風(fēng)格，為了完成任務(wù)以便盡早推出產(chǎn)品，代碼是想到哪就編到哪。在瘋狂的代碼編寫過程中，很少想到記錄下代碼要完成的功能。等產(chǎn)品交貨后，設(shè)計人員才會回去瀏覽代碼并進行“注釋”。

這樣做的問題是，這時已經(jīng)距離寫完代碼幾周甚至幾個月的時間了！對一些工程師來說記起昨天早餐吃的是什么都很難，更不用說兩周前寫的一段代碼了。最終結(jié)果是不準確的注釋說明，日后往往會引起誤解和缺陷。

這里的技巧當(dāng)然是在進行決策的同時隨時進行注釋。形式化的外部文檔注釋過程無疑會降低開發(fā)人員的進度，但向代碼庫中增加注釋真的不會占用更多時間。

開發(fā)人員能夠做的第一件事是先對代碼要做什么事寫一些注釋行，然后再寫代碼。如果實現(xiàn)發(fā)生了變化，開發(fā)人員可以立即更新注釋。在任何情況下，在編寫代碼的同時寫下注釋只會節(jié)省時間和增加條理性，從而更少發(fā)生錯誤，產(chǎn)品也能更快的上市。

技巧2——自動生成注釋文檔

盡管對代碼做了很詳細的注釋，但總是有生成外部文檔的要求，以便任何人不看代碼就能明白程序功能。這個要求經(jīng)常導(dǎo)致雙倍的注釋工作量。

幸運的是，市場上有現(xiàn)成的工具可以自動讀取代碼注釋、然后生成界面和代碼的其它文檔細節(jié)！幫助工程師避免必須做兩次相同的工作！一個具有這種功能的免費工具例子是Doxygen。

當(dāng)開發(fā)人員在編寫他們的代碼時，他們以指定方式格式化他們的注釋，并提供他們想要在外部文檔中展示的細節(jié)內(nèi)容。然后他們就可以運行Doxygen生成真實反映軟件內(nèi)注釋的html、rtf或pdf文檔。美妙的是如果你更新注釋，外部文檔也會自動更新！

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

雖然開發(fā)人員寫了代碼注釋，但如果注釋只是變量或函數(shù)名字的重復(fù)，會特別令人惱火。注釋應(yīng)該是描述性的文字，需要提供顯式意思之外更多的細節(jié)！

提供盡可能多的信息，而且不要忘了提及相關(guān)和關(guān)聯(lián)的變量或函數(shù)。開發(fā)人員應(yīng)該能夠只通過閱讀注釋就了解軟件的行為。圖1給出了一個注釋簡單映射數(shù)組代碼的例子。

圖1：映射數(shù)組

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

函數(shù)或變量注釋中包含如何使用它們的例子是很有用的。說應(yīng)該如何使用是一回事，但展示如何使用會讓人更清楚其用途。除了能夠減少錯誤使用對象的機會外，還能給人一個更清晰的印象。

圖2顯示了一個如何注釋函數(shù)的例子，它告訴開發(fā)人員應(yīng)該如何使用這個函數(shù)，從而避免了容易出錯的猜測過程，使人能夠更清晰地了解其用途。

img

圖2——使用例子

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

就像寫代碼一樣，為代碼開發(fā)注釋和文檔也應(yīng)該有個標(biāo)準。由于注釋標(biāo)準中不可能有許多條款，因此特別推薦向編寫代碼標(biāo)準靠攏。

也就是說確保小組中的每個成員以相同的方式進行注釋和歸檔，從而確保開發(fā)的易用性。開發(fā)人員應(yīng)該專注于解決手頭的設(shè)計問題，而不是費勁地去搞懂注釋。

技巧6——使用文檔模板

確保注釋遵循標(biāo)準的最容易的方法是為頭文件、源文件和支持文件創(chuàng)建模板。當(dāng)創(chuàng)建一個新模塊時，可以從模板入手，然后增加相關(guān)的信息。這將有助于確保文件信息塊、代碼段、函數(shù)和變量都用相同的格式注釋。

這種方法的最大優(yōu)勢是能夠節(jié)省大量時間，并有助于減少將一個模塊拷貝到另一個偽模板時發(fā)生的拷貝粘貼錯誤。為了讓生活更加輕松，我特意開發(fā)了可以用于定義頭文件和源文件的模板。

技巧7——圖表的作用

在一個項目的軟件實現(xiàn)階段開始之前，應(yīng)該有一個軟件設(shè)計階段。這個設(shè)計階段無疑會生成許多漂亮的圖（如流程圖和狀態(tài)機），并被用于實際實現(xiàn)。

雖然這些文檔作為軟件的開發(fā)路線圖，但在開發(fā)和測試過程中總會出現(xiàn)偏差！遺憾的是，這些變化很少會返回到圖表中。結(jié)果是設(shè)計文檔和軟件的不匹配！

在實現(xiàn)和測試階段將這些圖表放在手邊，以便發(fā)生上述偏差時這些圖表能及時得到更新。將這些圖表留到日后更新永遠不是正確的做法。雖然我們總是有返回去更新或修復(fù)的良好愿望，但這永遠不是合適的時機。

技巧8——保持注釋框使用的一致性

就像聽起來一樣奇怪，許多網(wǎng)絡(luò)爭論的內(nèi)容是何時、哪里使用何種類型的注釋框！不過嚴肅地講，不管你的信仰是什么，歸根到底是一致性問題。

如果一個團隊決定只使用/…/類型的注釋，那么就只使用這種類型。如果決定使用//類型，那就只使用//類型。

作者個人的觀點是傾向于使用/…/進行函數(shù)和模塊級說明，使用//進行函數(shù)代碼說明。不管選擇是什么，確保每次都按同樣的方式去做，這樣有助于生活更加輕松。

技巧9——使注釋更容易閱讀（即格式的美化）

為了確保避免誤解并由此產(chǎn)生代碼缺陷，使代碼保持結(jié)構(gòu)化和容易閱讀很重要。注釋也一樣。偶爾結(jié)構(gòu)化的注釋會使眼睛很難捕捉注釋，更難捕捉不在合適位置的內(nèi)容。應(yīng)該對注釋進行格式化處理，這樣如果代碼打印出來時（雖然現(xiàn)在不常打印，但我偶然仍會打印代碼）注釋就不會分到好幾頁上去。

在大塊注釋（如文件頭或函數(shù)注釋）中，如果你使用塊指示器，千萬不要包含進任何拖尾字符（如#或*），要不只會使文檔更新變得更加困難。

技巧10——嵌入圖像和圖表

借助自動化工具的使用，在注釋文檔中包含編碼標(biāo)準、縮寫詞、項目細節(jié)、要求和大量其它條款就成了可能。甚至能夠包含諸如流程圖等設(shè)計性圖表！

使用這類功能允許代碼庫不僅包含執(zhí)行代碼和邏輯，還包含你想要了解的項目所有內(nèi)容，并且所有信息都放在同一個地方。

審核編輯 ：李倩