华为软件规范笔记

华为软件规范笔记

（1）关于头文件说明

¹ 2-2：说明性文件（如头文件.h文件、.inc文件、.def文件、编译说明文件.cfg等）头部应进行注释，注释必须列出：版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等，头文件的注释中还应有函数功能简要说明。

示例：下面这段头文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。

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

  Copyright (C), 1988-1999, Huawei Tech. Co., Ltd.

  File name:      // 文件名

  Author:       Version:        Date: // 作者、版本及完成日期

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

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

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

  Others:         // 其它内容的说明

  Function List:  // 主要函数列表，每条记录应包括函数名及功能简要说明

    1. ....

  History:        // 修改历史记录列表，每条修改记录应包括修改日期、修改

                  // 者及修改内容简述  

    1. Date:

       Author:

       Modification:

    2. ...

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

（2）关于子函数头部的说明

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

示例：下面这段函数的注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。

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

  Function:       // 函数名称

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

  Calls:          // 被本函数调用的函数清单

  Called By:      // 调用本函数的函数清单

  Table Accessed: // 被访问的表（此项仅对于牵扯到数据库操作的程序）

  Table Updated:  // 被修改的表（此项仅对于牵扯到数据库操作的程序）

  Input:          // 输入参数说明，包括每个参数的作

                  // 用、取值说明及参数间关系。

  Output:         // 对输出参数的说明。

  Return:         // 函数返回值的说明

  Others:         // 其它说明

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

（3）关于注释

¹ 2-1：一般情况下，源程序有效注释量必须在20％以上。

说明：注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。

（4）常用反义词组

½ 3-3：用正确的反义词组命名具有互斥意义的变量或相反动作的函数等。

说明：下面是一些在软件中常用的反义词组。

add / remove       begin / end        create / destroy

insert / delete    first / last       get / release

increment / decrement                 put / get

add / delete       lock / unlock      open / close

min / max          old / new          start / stop

next / previous    source / target    show / hide

send / receive     source / destination

cut / paste        up / down

示例：

int  min_sum;

int  max_sum;

int  add_user( BYTE *user_name );

int  delete_user( BYTE *user_name );

（5）关于参数注意

6-1：防止将函数的参数作为工作变量。

说明：将函数的参数作为工作变量，有可能错误地改变参数内容，所以很危险。对必须改变的参数，最好先用局部变量代之，最后再将该局部变量的内容赋给该参数。

示例：下函数的实现不太好。

（6）关于。2016.7.11看完一遍，很好的手册，多看有益，在实践中践行。