CVS 实践: 用log 帮助查找需要文档的地方

作为事后的补救, 可以利用CVS的log功能找出某个开发人员所做出的发动, 针对这些改动的部分可以有的放失地为代码添加文档.

cvs log命令提供了很多选项, 可以限制分支, 时间, check in的作者等等信息, 如果项目组中的开发人员工作了一段时间之后需要集中为自己所作的工作进行文档化, 因为时间关系往往无从下手, 下面的命令可以收集这些自己作出的改动.

cvs log -wyour_name -N -S dir

其中-N选项是为了不输出每个文件的header信息, -S则是为了去掉那些你根本从未改动过的文件. dir是你可能做过修改的目录名, log会递归处理该目录下的所有文件.

这样就得到了自己修改过的文件的各个revision.

然后, 通过 一个图形化的CVS客户端工作如Tortoise CVS查看该文件所有版本的修改历史.

假设通过前面的命令知道了 1.1.1.1.2.5 是你所作的修改, 那么选中该版本和其前一个版本, 鼠标右键弹出上下文菜单, 选项其中的比较功能, 这会用一个比较工具突出显示你此次提交所作的改动, 这些地方正是最需要文档化的地方. 推荐使用 Araxis merge比较工具.

作为通用规则: 程序中典型地需要文档化的地方如:
1. 使用直接字面数字, 如12隐含地表示一年中的月份. 通常这是应该极力避免的编程风格, 应该用一个符号化的常量来代替这种做法.

2. 添加的代码行是为产品增加新特性, 新添加的代码隐含了一些假设和关于如何使用自身的消息.

对于C#程序, 最好把新添加的程序元素的注释直接写到
///

这种风格的注释里. 这种注释最容易被其它程序员看到, 从而真正起到作用.