最近一段时间由于工作需要,仔细研读了微软企业库的部分源码,不由得佩服这些大洋彼岸的同行们.先不谈代码的架构怎么样,起码在代码注释这一块,那叫一个专业啊.一个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.个人体验了一下,效果不错!更加详细的说明可参考本文最后的链接.
文章的最后还是放上一段个人比较喜爱的一句话,与君共勉:
傻瓜都可以写出机器能读懂的代码，但只有专业程序员才能写出人能读懂的代码
参考的文章: