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

暮鼓集    行走集

原作于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

部分RD习惯这样写：

// Add by XXX
// End XXX  

在绝大多数情况下，这没有问题，我的方法稍做改变，与之前所说的类似

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

这样写的好处是－在调试时可方便地将改写的代码关闭看原来MTK的效果，而不必去Mark掉。如果只增加了单行代码，并且无须解释就可以明其意，也可以这样写

...Your code // Add by XXX, YYYY-MM-DD  

如果习惯使用//Add //End的风格，请注意如下情况

// Add by XXX
#if defined(__PROJECT_A__)
...
#elif deined(__PROJECT_B__)
//End by XXX
#else
...
..
// Add by XXX
#endif
// End XXX  

最后这个#endif前后所加注释为多余，有经验的RD看了上半部分便知哪里是改过的，即使有问题，用版本工具一比较即可。

加了太多的// Add, //End会让代码看起来繁冗不堪，反而影响阅读。

还有一种情况，在一个函数中修改了很多地方

void func( void )
{
//Add by XXX
...
// End XXX
...
//Add by XXX
...
// End XXX
...
//Add by XXX
...
// End XXX
}

我建议，当一个函数中修改的部分超过1/3时，不如将此函数分开

#if 1 // Add by XXX, YYYY-MM-DD
void func( void )
{...}
#else // Orginal code
void func( void )
{...}
#endif