谈一谈修改代码时加注释的原则和方法

暮鼓集    行走集

原作于2008年06月01日，软件部培训稿

我们修改代码时少不了要加一些注释，这基本的原则是“言简意赅”，只要做到大家能看懂，在版本比较工具(BC及VSS)中能一目了然，这就可以了。

下面介绍一些方法供大家参考：

为某一项目或者某一MACRO配置而添加的代码

#if defined(__PROJECT_A__) // Add by XXX, YYYY-MM-DD
...Your codes
#elif defined(__PROJECT_B__) // Add by YYY, YYYY-MM-DD
...Other codes
#else
...Orginal codes
#endif  

为修改某一Bug而添加并通用于各项目的代码

#if 1 // Add by XXX, YYYY-MM-DD
...Your codes
#else
...Original codes
#endif  

如果需要说明是为了什么而修改，也可将注释单列一行。

// Add by XXX, YYYY-MM-DD
// ... Description
// ...

每行的长度不要太长，建议为80个字符，按照公司规定的流程，如果是修改Bug管理系统中的问题，必须注明Bug单的编号。

  // Add by XXX, YYYY-MM-DD, Bug No.QSXXXXXX
<