首页 > 编程语言 >C语言编程规范——注释

C语言编程规范——注释

时间:2024-05-02 23:23:44浏览次数:28  
标签:函数 int 代码 编程 C语言 注释 修改 printf

一、注释简介

一般情况下,源程序有效注释量必须在20%以上。注释的目的是解释代码的目的、功能和采用的方法,提供代码以外的信息,帮助读者理解代码,防止没必要的重复注释信息。

二、注释类型

1.单行注释

将注释放在双斜杠 // 后面,从双斜杠到行尾都属于注释。

#include<stdio.h>
int main()
{
	//printf("hello\n");   这是一整行注释
	printf("world\n");    //双斜杠后面为注释
	return 0;
}

2.多行注释

  • 将注释放在 /*...*/ 之间,内部可以分多行。
#include<stdio.h>
int main()
{
	/*
	printf("hello\n"); 
	printf("world\n");
	这是多行注释
	*/
	return 0;
}
  • 多行注释也可以放在行内(如对参数进行说明)
int print(int arr, int sz/*数组元素*/,char a);
  • /*/ 的这个注释不支持嵌套注释, / 开始注释后,遇到第⼀个 */ 就认为注释结束了。
#include<stdio.h>
int main()
{
	/*
	printf("hello");
	printf("world");  /*注释到此结束*/
	printf("\n");
	*/
	return 0;
}

3.条件编译注释

用#if 0 配合 #endif 可实现代码的成块注释。条件编译指令#if后面跟整型常量表达式。如果表达式为非零,则表达式为真,编译器条件执行代码块;反之,编译器忽略代码块。

#include<stdio.h>
int main()
{
#if 0
	printf("ABC\n");
#endif
 
#if 1
	printf("abc\n");
#endif
	return 0;
}

//第一个代码块被忽略,第二个代码块执行,输出abc;
//如果想要换成执行第一个代码块,输出ABC,则只需将“1”和“0”位置互换

三、程序文件注释

头文件注释

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

/**
 * File name: test.h    // 文件名
 * Author:laubon    
 * Version:V1.0    
 * Date:2024.5.1   		// 完成日期
 * Description:    		// 用于详细说明此程序文件完成的主要功能,与其他模块或函数的接口,
                   		// 输出值、取值范围、含义及参数间的控制、顺序、独立或依赖等关系
                   
 * Others:         		// 其它内容的说明
 * Function List:  		// 主要函数列表,每条记录应包括函数名及功能简要说明

    1. func1....
    2. func2....
    ....
 
 * History:        		// 修改历史记录列表,每条修改记录应包括修改日期、修改者及修改内容简述
                   		 
    1. Date: 
       Author:
       Modification:
    2. ...
* CopyRight (c)  2023-2024   [email protected]   All Right Reseverd
*/

函数头部注释

函数的目的/功能、输入参数、输出参数、返回值、调用关系(函数、表)等。

/**  
 * Function:        // 函数名称
 * Description:     // 函数功能、性能等的描述
 * Calls:           // 被本函数调用的函数清单
 * Called By:       // 调用本函数的函数清单
 * Table Accessed:  // 被访问的表(此项仅对于牵扯到数据库操作的程序) 
 * Table Updated:   // 被修改的表(此项仅对于牵扯到数据库操作的程序)
 * Input:           // 输入参数说明,包括每个参数的作
                    // 用、取值说明及参数间关系。

 * Output:          // 对输出参数的说明。
 * Return:          // 函数返回值的说明
 * Others:          // 其它说明
 * CopyRight (c)  2023-2024   [email protected]   All Right Reseverd
 */

源文件注释

版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。

/** 
 * FileName:  test.c
 * Author:    XIN-Mr     
 * Version :  V1.0      
 * Date:      2024.5.1
 * Description:             // 模块描述
 * Function List:           // 主要函数及其功能
    1. ....
 
 * History:        		// 修改历史记录列表,每条修改记录应包括修改日期、修改者及修改内容简述
                   		 
    1. Date: 
       Author:
       Modification:
    2. ...
 * CopyRight (c)  2023-2024   [email protected]   All Right Reseverd 
 */

四、注释时的注意事项

  1. 注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面。除非必要,不应在代码或表达中间插入注释,否则容易使代码可理解性变差。
  2. 变量、常量、宏的注释应放在其上方相邻位置或右方。
  3. 注释的内容要清楚、明了,含义准确,防止注释二义性。
  4. 对于所有有物理含义的变量、常量,如果其命名不是充分自注释的,在声明时都必须加以注释,说明其物理含义。
  5. 数据结构声明( 包括数组、结构、类、枚举等) ,如果其命名不是充分自注释的,必须加以注释。对数据结构的注释应放在其上方相邻位置,不可放在下面;对结构中的每个域的注释放在此域的右方。
  6. 全局变量要有较详细的注释,包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明
  7. 注释格式尽量统一,建议使用“/* …… */”
  8. 注释应考虑程序易读及外观排版的因素,使用的语言若是中、英兼有的,建议多使用中文,除非能用非常流利准确的英文表达——注释语言不统一,影响程序易读性和外观排版,出于对维护人员的考虑,建议使用中文。

标签:函数,int,代码,编程,C语言,注释,修改,printf
From: https://www.cnblogs.com/banon/p/18170727

相关文章

  • Socket网络编程
    Socket编程为了实现两台不同的机器能够进行通信,所有要使用到网络编程IP地址与端口号IP地址:用于标识网络上主机的位置,每台网络上的设备都有唯一的ip地址。端口号:用于标识主机上的哪个应用程序,一台主机上运行的很多应用程序,该数据是传送给哪个应用程序使用的通过端口号标识。......
  • c语言实现vector及其相关函数(自存)
    #include<stdio.h>#include<stdlib.h>#definePREALLOC_MAX1024#defineDEFAULT_CAPACITY8typedefintE;typedefstruct{E*elements;//指向堆空间的数组intsize;//元素的个数intcapacity;//数组的容量}Vector;voidpush_back(Vect......
  • 04. C语言数据使用方式
    【C语言简介】计算机的运行由CPU指令控制,为了让计算机执行指定功能,需要将这些功能对应的指令数据集中存储在一起,制作为一个计算机文件,这个文件称为程序,CPU通过读取程序中的指令确定要执行的功能,制作程序时无需直接编写指令数据和数学数据,这些数据使用代码表示,从而方便记忆和编写,......
  • idea在类和接口上面自动生成注释
    详细教程:https://www.cnblogs.com/ya-qiang/p/9462766.html1、File>>Settings…>>Editor>>FileandCodeTemplates/***@Auther:Zxd*@Date:${YEAR}/${MONTH}/${DAY}${TIME}*@Description:*/  ......
  • C语言中四舍五入问题总结
    C语言中四舍五入问题的总结在C语言中大部分情况下都是不需要四舍五入的。除了一种情况:在使用输出函数printf()限制浮点型输出的小数位个数eg:printf("%0.2f",1.567);//输出的结果是1.57其他情况下都不需要四舍五入,比如自动转换在不同类型的混合运算中,编译器也会自动地转......
  • shell编程
    !/bin/bashset-u-e安全export环境变量cat/porc/$PID/export位置变量$0:表示脚本或命令本身的名称。$1,$2,$3,...:表示第一个、第二个、第三个等参数的值。$*或$@:表示所有位置参数的列表。$#:表示传递给脚本或命令的位置参数的个数。echo$[12^4]=8异......
  • 五个重要的编程原则让你写出高质量代码
    Therearefiveprinciplesthatyoushouldconform.1:Singleresponsibilityprinciple.各司其职,一个对象不要封装的太复杂,设计的时候要考虑好哪些功能属于这个对象,不要将一个对象弄得太复杂,当你意识到一个对象承担了太多责任的时候,尝试分开它,减小耦合度,以便维护。2:Open-Clo......
  • C语言程序设计——字符串典型题练习
    1、计算一个字符串中最大的重复子串的字符的数量/********************************************************************* name : CalSubStrMaxCnt* function:计算一个字符串中最大的重复子串的字符的数量* argument:* @str:需要查找的字符串的地址* * ret......
  • C#的基于.net framework的Dll模块编程(五) - 编程手把手系列文章
          这次继续这个系列的介绍: 一、使用DLL类库的方法;1)静态类;先引用该类库,然后声明命名空间,然后就能够进行使用了。   2)动态类;先引用该类库,然后声明命名空间,然后能够进行使用了。  3)窗体;只能在Winf......
  • C语言实现文件加密
    原理加密文本,或加密二进制文件,可以选择的一个最小加密单元是单个字符(或者说,一个byte)。将每个byte和31做异或运算,得到加密结果。再做一次异或则得以恢复原始数据。加密文本-控制台程序#include<stdio.h>#include<stdlib.h>voidencrypt(char*message){charc;......