注釋的力量
最近一段時間由于工作需要,仔細研讀了微軟企業庫的部分源碼,不由得佩服這些大洋彼岸的同行們.先不談代碼的架構怎么樣,起碼在代碼注釋這一塊,那叫一個專業啊.一個200行的源文件150行注釋50行代碼是常有的事.注釋量不僅多,質量也高.我的很多困惑都是通過閱讀代碼注釋得以解答的.
這年頭,代碼注釋的方式基本都是采用以///開頭的xml注釋方式了.在visual studio里,連續輸入三個///,編輯器會自動補全剩下的部分.默認使用的是summary標簽.如果是方法則可能還會有param與returns標簽.這也是我們最常用到的三個標簽.難道xml注釋方式只有這三種標簽嗎?顯然不是.當你再輸入一個<的時候,編輯器就會自動提示還可以使用的標簽.粗粗一算,整整20個,可真不少呀.
上網查閱了一下,其實常用的只有11個標簽左右,下面大概介紹一下
summary,被注釋對象的摘要
example,展現被注釋對象的一個示例
c,在注釋中寫代碼,當代碼只有一行的時候使用.通常與example配合使用
code,在注釋中寫代碼,當代碼有多行時使用.通常與example配合使用
param,被注釋對像的參數,有一個name屬性,指定注釋哪一個參數
returns,被注釋對像的返回值
exception,被注釋對象執行時可能拋出的異常.有一個cref屬性,指定異常類型
remarks,被注釋對象的備注.用來詳細描述被注釋對象
para,段落標簽. 類似于HTML里的P標簽.寫在里面的內容會作為單獨的一段
paramref,引用參數.在摘要,備注或其它地方如果要對參數進行說明,如果將參數以該標簽包裹,最終生成的chm文檔時會生成一個超鍵接指向該參數,有一個name屬性,指定參數名稱
see,參考標簽.有一個cref屬性,指定參考類型名.
以上11個標簽在使用上各不相同.首先,只有被summary包裹或param,returns,para這四個標簽才能在visual studio的智能感知里看到效果.你單獨寫一個remarks標簽vs是感知不到的,其它的注釋效果需要用工具生成chm后才能看到.其次,summary,example,returns,remarks,para會成普通文字格式,c,code會生成代碼格式,exception,see會生成一個超鏈接鏈向指定類型.更加詳細的說明可參考本文最后的鏈接.
現在再來談一談注釋生成工具的使用.最早的工具是微軟的御用工具DocGen,開源的NDoc,還有一個通用工具DoxyGen,但是現在這幾個要么不好用,生成的文檔不符合.net習慣,要么軟件停止更新了,不好獲取了.現在用的比較多的是Sandcastle.個人體驗了一下,效果不錯!更加詳細的說明可參考本文最后的鏈接.
文章的最后還是放上一段個人比較喜愛的一句話,與君共勉:
傻瓜都可以寫出機器能讀懂的代碼，但只有專業程序員才能寫出人能讀懂的代碼
參考的文章:
浙公網安備 33010602011771號