C语言编程规范1: 注释

    我们不仅要写高效的代码，还要写可读性很强的代码，随着我们所开发系统的复杂性的不断提高，这就要求我们所写的程序具有3个特性：1、可读性；2、可多人协作性；3、可移植性。但是，像我们这样电子专业毕业的学生，都没有接受过“软件设计方法论”、“操作系统原理”等课程的深入训练，这就使我们所写的程序与软件专业工程师所写的程序具有较大的差距，这些问题使得公司在程序的代码维护上面临着诸多的困难。这种窘境需要打破！

    本文从“C语言编程规范”着手，着重讲授如何书写规范性的C语言程序代码，文中所举实例，均为知名公司所采用的C语言规范。按照本系列课程严格要求自己规范性编写C语言代码，可使得我们书写的程序给人耳目一新的感觉，易于阅读，并避免潜在的逻辑性错误的发生。

    注释：
    注释是源码程序中非常重要的一部分，一般情况下，源程序有效注释量必须在15％以上。注释的原则是有助于对程序的阅读理解，所以注释语言必须准确、易懂、简洁。注释不宜太多也不能太少，注释的内容要清楚、明了，含义准确，防止注释二义性，该加的地方一定要加，但不必要的地方一定不要加。
 
    A、C文件描述 

    模块描述中应该包括。版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等。 例如：

/***********************************************************/

Module Name: //模块的名字

Module Date: //生成日期

Module Auth: //作者名字

Description: // 用于详细说明此程序文件完成的主要功能，与其他模块

                // 或函数的接口，输出值、取值范围、含义及参数间的控

                // 制、顺序、独立或依赖等关系

Others:         // 其它内容的说明

Revision History:

Date Rel Ver. Notes

月/日/年 x.x    //所进行的修改

***********************************************************/

/*----------------Includes---------------*/

//包含的头文件

/*------------Local Variables----------- */

//定义一些本地变量

/*------Local Structures and Typedefs ---*/

//要使用的一些数据结构

/*-----------Extern Variables -----------*/

//使用到的一些外部变量

/*-------------Definitions---------------*/

//一些#defines及具体的函数实现

    B、头文件描述

    头文件一般包括了数据结构的定义，函数原形的说明，宏定义等，不许包含函数体和变量实体，文件名使用缺省的后缀 .h ，头文件的注释可如下：

#ifndef MODEL_H

#define MODEL_H

/***********************************************************

Module Name: model.h

Module Date: month/day/year

Module Auth: your name

Description: a short introduction of this module.

Revision History:

Date Rel Ver. Notes

month/day/year x.x [e.g.] Module created

***********************************************************/

/*----------------Includes---------------*/

//the head files that were included

//[e.g.] #include "head.h"

/*---------Structures and Typedefs-------*/

/*[e.g.] struct model{

char MemberOne;

int MemberTwo;

char MemberThree[3];

struct module *MemberFour;

}

enum BOOL {TRUE ,FALSE };

typedef struct module MODULE;

*/

/*---------------Defines-----------------*/

//[e.g.] #define MODLE 2

/*----------extern variables-------------*/

//the variables that were defined in other modules

//[e.g.] estern char ExternVariable;

/*-----External Function Prototypes------*/

/* External Function Prototypes */

//the functions that were implemented in other modules

//[e.g.] extern unsigned char model(int Input[2]);

#endif

    C、函数描述

    函数头部应进行注释，列出：函数的目的/功能、输入参数、输出参数、返回值、调用关（函数、表）等。 例如：

/***********************************************************

Function Name:         //函数名

Function Description:  //函数功能、性能等的描述

Inputs:                //输入参数说明，包括每个参数的作用、取值说明及参数间关系。

Outputs:               //对输出参数的说明

Notes:                 //本函数调用的函数清单及其他

************************************************************/

 

    D、其它注释

    ①通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构，使代码成为自注释的。说明：清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释。

    ②注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。

    ③对于所有有物理含义的变量、常量，数据结构声明(包括数组、结构、类、枚举等)，如果其命名不是充分自注释的，在声明时都必须加以注释，说明其物理含义。变量、常量、宏的注释应放在其上方相邻位置或右方。 例如：

/* active statistic task number */

#define MAX_ACT_TASK_NUMBER 1000

#define MAX_ACT_TASK_NUMBER 1000 // active statistic task number

    ④全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明。

    ⑤将注释与其上面的代码用空行隔开。 例如：

/* code one comments */

program code one

/* code two comments */

program code two

    ⑥在代码的功能、意图层次上进行注释，提供有用、额外的信息。 说明：注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码，防止没必要的重复注释信息。 例如：如下注释意义不大。

/* if receive_flag is TRUE */

if (receive_flag)

    而如下的注释则给出了额外有用的信息。

/* if mtp receive a message from links */

if (receive_flag)

原创性文章，转载请注明出处 http://user.qzone.qq.com/2756567163。 

CSDN：http://blog.csdn.net/qingwufeiyang12346。