C语言编程规范--------2 注释

2.1 注释的原则

注释的目的是解释代码的目的、功能和采用的方法,提供代码以外的信息,帮助读者理解代码,防止没必要的重复注释信息。 示例:如下注释意义不大。

/* if receive_flag is TRUE */

if (receive_flag)

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

/* if mtp receive a message from links */

if (receive_flag)

 

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.3 源文件头部应进行注释

源文件头部应进行注释,列出:版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。

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

/**

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

 * FileName: test.cpp

 * Author:        Version :          Date:

 * Description:     // 模块描述

 * Version:         // 版本信息

 * Function List:   // 主要函数及其功能

    1. -------

 * History:         // 历史修改记录

      <author>  <time>   <version >   <desc>

      David    96/10/12     1.0     build this moudle

 */

说明:Description一项描述本文件的内容、功能、内部各部分之间的关系及本文件与其它文件关系等。History是修改历史记录列表,每条修改记录应包括修改日期、修改者及修改内容简述。

 

2.4 函数头部应进行注释

函数头部应进行注释,列出:函数的目的/ 功能、输入参数、输出参数、返回值、调用关系(函数、表)等。

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

/**

 * Function:       // 函数名称

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

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

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

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

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

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

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

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

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

 * Others:         // 其它说明

 */

对于某些函数,其部分参数为传入值,而部分参数为传出值,所以对参数要详细说明该参数是入口参数,还是出口参数,对于某些意义不明确的参数还要做详细说明(例如:以角度作为参数时,要说明该角度参数是以弧度(PI),还是以度为单位),对既是入口又是出口的变量应该在入口和出口处同时标明。等等。

在注释中详细注明函数的适当调用方法,对于返回值的处理方法等。在注释中要强调调用时的危险方面,可能出错的地方。

 

2.5 进行注释时的注意事项

(1)建议边写代码边注释,修改代码同时修改相应的注释,以保证注释与代码的一致性。不再有用的注释要删除。

(2)注释的内容要清楚、明了,含义准确,防止注释二义性。说明:错误的注释不但无益反而有害。

(3)避免在注释中使用缩写,特别是非常用缩写。在使用缩写时或之前,应对缩写进行必要的说明。

(4)注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面。除非必要,不应在代码或表达中间插入注释,否则容易使代码可理解性变差。

示例:如下例子不符合规范。

例1:

/* get replicate sub system index and net indicator */

 

repssn_ind = ssn_data[index].repssn_index;

repssn_ni = ssn_data[index].ni;

例2:

repssn_ind = ssn_data[index].repssn_index;

repssn_ni = ssn_data[index].ni;

/* get replicate sub system index and net indicator */

应如下书写

/* get replicate sub system index and net indicator */

repssn_ind = ssn_data[index].repssn_index;

repssn_ni = ssn_data[index].ni;

(5)对于所有有物理含义的变量、常量,如果其命名不是充分自注释的,在声明时都必须加以注释,说明其物理含义。变量、常量、宏的注释应放在其上方相邻位置或右方。

示例:

/* active statistic task number */

#define MAX_ACT_TASK_NUMBER 1000

#define MAX_ACT_TASK_NUMBER 1000 /* active statistic task number */

(6)数据结构声明( 包括数组、结构、类、枚举等) ,如果其命名不是充分自注释的,必须加以注释。对数据结构的注释应放在其上方相邻位置,不可放在下面;对结构中的每个域的注释放在此域的右方。

示例:可按如下形式说明枚举/数据/联合结构。

/* sccp interface with sccp user primitive message name */

enum  SCCP_USER_PRIMITIVE

{

    N_UNITDATA_IND, /* sccp notify sccp user unit data come */

    N_NOTICE_IND,   /* sccp notify user the No.7 network can not */

                    /* transmission this message */

    N_UNITDATA_REQ, /* sccp user's unit data transmission request*/

};

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

示例:

/* The ErrorCode when SCCP translate */

/* Global Title failure, as follows */      // 变量作用、含义

/* 0 - SUCCESS   1 - GT Table error */

/* 2 - GT error  Others - no use  */       // 变量取值范围

/* only  function  SCCPTranslate() in */

/* this modual can modify it,  and  other */

/* module can visit it through call */

/* the  function GetGTTransErrorCode() */    // 使用方法

BYTE g_GTTranErrorCode;

(8)注释与所描述内容进行同样的缩排,让程序排版整齐,并方便注释的阅读与理解。

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

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

}

(9)将注释与其上面的代码用空行隔开。

示例:如下例子,显得代码过于紧凑。

/* code one comments */

program code one

/* code two comments */

program code two

应如下书写

/* code one comments */

program code one

 

/* code two comments */

program code two

(10)对变量的定义和分支语句(条件分支、循环语句等)必须编写注释。这些语句往往是程序实现某一特定功能的关键,对于维护人员来说,良好的注释帮助更好的理解程序,有时甚至优于看设计文档。

(11)对于switch 语句下的case 语句,如果因为特殊情况需要处理完一个case 后进入下一个case 处理(即上一个case后无break),必须在该case 语句处理完、下一个case 语句前加上明确的注释,以清楚表达程序编写者的意图,有效防止无故遗漏break语句(可避免后期维护人员对此感到迷惑:原程序员是遗漏了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;

...

(12)在程序块的结束行右方加注释标记,以表明某程序块的结束。当代码段较长,特别是多重嵌套时,这样做可以使代码更清晰,更便于阅读。示例:参见如下例子。

if (...)

{

    program code

    while (index < MAX_INDEX)

    {

        program code

    } /* end of while (index < MAX_INDEX) */ // 指明该条while语句结束

} /* end of  if (...)*/ // 指明是哪条if语句结束

(13)在顺序执行的程序中,每隔3—5行语句,应当加一个注释,注明这一段语句所组成的小模块的作用。对于自己的一些比较独特的思想要求在注释中标明。

(14)注释格式尽量统一,建议使用“/* …… */”。

(15)注释应考虑程序易读及外观排版的因素,使用的语言若是中、英兼有的,建议多使用中文,除非能用非常流利准确的英文表达——注释语言不统一,影响程序易读性和外观排版,出于对维护人员的考虑,建议使用中文。

转载于:https://www.cnblogs.com/mrsandstorm/p/5663456.html

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/284214.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

备战金九银十:RabbitMQ有5种工作模式(6)

RabbitMQ是实现了高级消息队列协议&#xff08;AMQP&#xff09;的开源消息代理软件&#xff08;亦称面向消息的中间件&#xff09;。RabbitMQ服务器是用Erlang语言编写的&#xff0c;而集群和故障转移是构建在开放电信平台框架上的。所有主要的编程语言均有与代理接口通讯的客…

【GlobalMapper精品教程】020:Lidar点云数据分类(自动分类、手动分类)案例详解

航测点云通常跟DSM一致,即包含植被、房屋等信息,必须进行点云分类、过滤,才能生成准确的高程点、等高线和DEM等地形数据。本文以案例的形式详细讲解globalmapper23中点云工具及使用方法。 文章目录 1. 点云分类2. 创建地面高程格网3. 地形绘制4. 格网转点云5. 点云抽稀6. 点…

社交网络图中结点的“重要性“计算(Dijkstra + SPFA + Floyd + 模板)

题目链接&#xff1a; 无 题目大意&#xff1a; 求一个点到其他所有点的最短距离和&#xff0c;保证图连通。 解题过程&#xff1a; 刚开始用 Floyd 水过的&#xff0c;后来用换了几种方法&#xff0c;不错的模板题&#xff0c;Floyd 的时候&#xff0c;要用 vector 存边&#…

web布局固定宽度+变化宽度实现思路

前言 页面当中常规布局我想大家都会的&#xff0c;但有些布局是常规布局中实现不了的&#xff0c;比如变宽和固宽结合的&#xff0c;需要实现(300px)&#xff0b;(100%&#xff0d;300px)的两列布局。以下样式代码前提均为盒模型为border-sizing 的前提下。 html部分 <div c…

CSS3 nth 伪类选择器

考察下面的 HTML 代码片段&#xff1a; <div><section>section 1</section><section>section 2</section><ul><li>item 1</li><li><ul><li>sub item 1</li><li>sub item 2</li><li>…

RedisCluster的安装、部署、扩容和 Java客户端调用

Redis下载 官网地址&#xff1a;http://redis.io/ 中文官网地址&#xff1a;http://www.redis.cn/ 下载地址&#xff1a;http://download.redis.io/releases/ 安装 # &#xff08;三台&#xff09;安装 C 语言需要的 GCC 环境 yum install -y gcc-c yum install -y wget # 下…

【CloudCompare教程】001:CloudCompare中文版下载与安装图文教程

CloudCompare是一款功能强大的点云后处理软件,本文讲解CloudCompare中文版下载与安装方法。 文章目录 一、CloudCompare下载地址二、CloudCompare安装教程三、CloudCompare中文设置一、CloudCompare下载地址 官方下载地址:http://www.danielgm.net/cc/release/ 二、CloudComp…

ML.NET相关资源整理

在人工智能领域&#xff0c;无论是机器学习&#xff0c;还是深度学习等&#xff0c;Python编程语言都是绝对的主流&#xff0c;尽管底层都是C实现的&#xff0c;似乎人工智能和C#/F#编程语言没什么关系。在人工智能的工程实现&#xff0c;通常都是将Python训练好的人工智能模型…

带参数的宏替换

带参数的宏替换因各种需求叠加&#xff0c;替换规则很怪异&#xff1a; 1、首先将实参替换形参&#xff0c;并展开宏 2、如果1步展开后&#xff0c;有#或者##&#xff0c;那么停止替换。 3、如果1步展开后&#xff0c;没有#或者##&#xff0c;且参数也是宏&#xff0c;那么继续…

JAVA学习日志(7-1-继承)

为什么80%的码农都做不了架构师&#xff1f;>>> 继承 1.提高代码复用性 2.让类与类之间产生关系&#xff0c;有了这个关系才有了多态的特性 **不要为了获取其他类的功能&#xff0c;简化代码而继承&#xff0c; 必须是类与类之间有所属关系才可以继承&#xff0c;所…

BZOJ 1370: [Baltic2003]Gang团伙 [并查集 拆点 | 种类并查集WA]

题意&#xff1a; 朋友的朋友是朋友&#xff0c;敌人的敌人是朋友&#xff1b;朋友形成团伙&#xff0c;求最多有多少团伙 种类并查集WA了一节课&#xff0c;原因是&#xff0c;只有那两种关系才成立&#xff0c;诸如朋友的敌人是朋友之类的都不成立&#xff01; 所以拆点做吧 …

常见Lidar点云数据处理及可视化软件汇总

常见的点云处理及可视化软件有&#xff1a; CloudCompare、Globalmapper、Pix4d、ArcGIS&#xff08;Pro&#xff09;、Lidar 360、PCL等等。 文章目录1. CloudCompare2. Globalmapper3. Pix4d4. ArcGIS&#xff08;Pro&#xff09;5. Lidar 3606. PCL1. CloudCompare CloudCo…

Spring 自带工具类汇总

断言 断言是一个逻辑判断&#xff0c;用于检查不应该发生的情况 Assert 关键字在 JDK1.4 中引入&#xff0c;可通过 JVM 参数-enableassertions开启 SpringBoot 中提供了 Assert 断言工具类&#xff0c;通常用于数据合法性检查 // 要求参数 object 必须为非空&#xff08;Not…

解决new Thread().Start导致高并发CPU 100%的问题

背景之前接手一个项目的时候&#xff0c;发现到处是new Thread(()>{ //do something }).Start();这么做的目的&#xff0c;无非是为了减少页面等待时间提高用户体验&#xff0c;把一些浪费时间的操作放到新线程中在后台运行。问题但是这样带来的问题是大量的创建线程&#x…

基于 HTML5 Canvas 绘制的电信网络拓扑图

电信网结构&#xff08;telecommunication network structure&#xff09;是指电信网各种网路单元按技术要求和经济原则进行组合配置的组合逻辑和配置形式。组合逻辑描述网路功能的体系结构&#xff0c;配置形式描述网路单元的邻接关系&#xff0c;即以交换中心&#xff08;或节…

网络相关配置,SSH服务,bash, 元字符

作业一&#xff1a;临时配置网络&#xff08;ip&#xff0c;网关&#xff0c;dns&#xff09;永久配置 设置IP和掩码ifconfig eth0 192.168.2.2 netmask 255.255.255.0设置网关route add default gw 192.168.2.10[rootbogon ~]# cat /etc/sysconfig/network-scripts/ifcfg-eth0…

【GlobalMapper精品教程】021:利用控制点校正栅格图像

本文讲解GlobalMapper中利用控制点校正栅格图像的方法,数据为配套实验数据包中的data021.rar。 文章目录 一、结果预览二、校正过程【推荐阅读】:ArcGIS实验教程——实验二:ArcGIS地理配准完整操作步骤 一、结果预览 二、校正过程 (1)打开图像。选择实验包中的待校正的栅…

[笔记]提升R的性能和突破内存限制的技巧

本文为雪晴数据网《R语言大规模数据分析实战》 http://www.xueqing.tv/course/56 的课程学习笔记。 该课程目前更新到“第2章 Microsoft R Server简介”的微软数据科学家介绍MRS&#xff0c;后续教学主要是关于MRS的内容&#xff0c;再另外学习&#xff0c;所以本文只学习“第1…