关于程序注释的基础知识[三]

¹2-12：注释与所描述内容进行同样的缩排。

说明：可使程序排版整齐，并方便注释的阅读与理解。

示例：如下例子，排版不整齐，阅读稍感不方便。

 

void example_fun( void )

{

/* code one comments */

    CodeBlock One

 

        /* code two comments */

    CodeBlock Two

}

 

应改为如下布局:

void example_fun( void )

{

    /* code one comments */

    CodeBlock One

 

    /* code two comments */

    CodeBlock Two

}

 

¹2-13：将注释与其上面的代码用空行隔开。

示例：如下例子，显得代码过于紧凑。

/* code one comments */

program code one

/* code two comments */

program code two

应如下书写

/* code one comments */

program code one

 

/* code two comments */

program code two

 

¹2-14：对变量的定义和分支语句（条件分支、循环语句等）必须编写注释。

说明：这些语句往往是程序实现某一特定功能的关键，对于维护人员来说，良好的注释帮助更好的理解程序，有时甚至优于看设计文档。

 

¹2-15：对于switch语句下的case语句，如果因为特殊情况需要处理完一个case后进入下一个case处理，必须在该case语句处理完、下一个case语句前加上明确的注释。

说明：这样比较清楚程序编写者的意图，有效防止无故遗漏break语句。

示例（注意斜体加粗部分）：

case CMD_UP:  

    ProcessUp();

    break;

 

case CMD_DOWN:

    ProcessDown();

    break;

 

case CMD_FWD: 

    ProcessFwd();

   

if (...)

{

    ...

    break;

}

else

{

    ProcessCFW_B();   // now jump into case CMD_A

}

 

case CMD_A:   

    ProcessA();   

    break;

 

case CMD_B:   

    ProcessB();   

    break;

 

case CMD_C:   

    ProcessC();   

         break;

 

case CMD_D:   

    ProcessD();   

    break;

...