挖井

类库大魔王的挖井日记

挖一口属于自己的井


Write well documented code

  在开始决定使用doxygen后,一直有种隐形的强迫之力,促使我为自己写的代码作好注释。今天经过一番小小的努力后,到晚上加班时,终于可以warning free地用doxygen为我那个工程生成暂时令自己还比较满意的文档了。心里不免有些小小的成就感,心想这样的场合下写的代码,就是应该这样作好注释,为文件、类、变量、函数等等各种元素进行标记。
  现在我用doxygen的方式还是比较落后的。先用doxywizard生成一个doxfile,然后把这个doxfile添加到VC的解决方案里,注意保存路径也是要和解决方案一起的,这样以后方便。再在VS的IDE里有个外部工具菜单项,添加一条指向doxygen.exe,参数当然是doxfile,路径是和解决方案的一样,运行目录也是和解决方案的一样,这样就在菜单上多出一项doxygen来。为图方便,可以写几个自动添加注释的宏,并把它们绑定到快捷键上去。目前我自己用的有为文件、类、函数以及普通目的几种定制了宏,定制宏的目的是一方面可以生成符合doxygen要求的格式注释,另一方面有些内容是可以自动填好的,比如文件名、作者、日期等等,当然这样的宏还是很低级很落后的,最好是能把这样的功能跟Visual Assist X之类的插件集成在一起,可以自动识别出函数名、类名等更高级的信息,并生成相应的注释,不过现在在还没找到更好的办法之前,就先这样将就一下吧。最后就是点击那个菜单项,运行doxygen,生成文档。
  doxygen提供了很多选项,也支持非常多的关键字。在使用的时候,我也是一边摸索一边尝试,唯一的资料就是它自带的文档,在开源的项目中算是很不错的了。不过始终让我觉得郁闷的是,为什么中文的老有问题,好在现在有一个别人的自编译版本,1.5.1的能比较完整地支持中文了,先暂时这么用着。
  另外有些经验。对于同一项目中不同目录下的同名文件,可以通过写路径来让doxygen区分出两个文件的不同,而且要注意的是,这个路径它是大小写敏感的。对于文件名唯一的文件,只要写出文件名即可。
  注释写在头文件中比写在实现文件中要好,而且最好声明和实现完全一致,比如函数参数列表。注释中标识参数时,只要写参数变量名即可,不用写定义的类型,而且变量名要和声明时的完全一致。
  doxygen支持todo list,它会把它单独列出来,比较方便,当然现在的MS和CodeGear的IDE也有对todo list支持。
  最好对每个有点作用的变量、函数、文件、类(结构、枚举)、宏定义等都作注释,这样看起来比较舒服。
  对于ATL中使用STDMETHOD(xxx)(yy,zz)这类形式的声明,如果doxygen认不出来,可以改成STDMETHODIMPL xxx(yy,zz)这样的形式,就可以了,不过我没试过其它选项,说不定哪里设置一下,前面的那种形式就能很好地识别出来了。
  最好装上Graphviz,让doxygen使用它来生成类图、被调用图,很好,很强大。
  还有就是要坚持,要循序渐进,在新定义一个变量,一个类,一个函数时,就给它添加注释,嗯,这样就能写出一份well documented code了!

本文地址:

https://minidump.info/blog/2007/11/write-well-documented-code/

上一篇

托小妞买了条项链

  今天小妞把项链给了我。这是我前些天托小妞去香港的时候带的,周大福的,在我的要求下,据小妞说这链子是加长18寸的,应该能够我妈带了,呵呵。原价是一千一,可以打九折,就是九百九了。其实最开始的时候,我还以为只要三四五百就够了,后来跟小妞说的时候就随口提高了上限,说一千以下就可以了。看光泽还是不...…

Water 全文阅读
下一篇

XML,很好,很强大!

  今天发现有些内容(比如针对某文档的评论内容)显示,是一条一条的,用表格是种不错的选择。如果在MFC写的程序里,比较方便的做法是用ListView来显示,不过随后到实际要动手的时候发现,用ListView并不能够满足需求,因为一般的ListView只能显示一行内容,而我需要的是在固定列宽的限...…

Software 全文阅读