C语言编程规范——注释
一、注释简介
一般情况下，源程序有效注释量必须在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 User_laubon@163.com All Right Reseverd
*/
函数头部注释
函数的目的/功能、输入参数、输出参数、返回值、调用关系（函数、表）等。
/**
* Function: // 函数名称
* Description: // 函数功能、性能等的描述
* Calls: // 被本函数调用的函数清单
* Called By: // 调用本函数的函数清单
* Table Accessed: // 被访问的表(此项仅对于牵扯到数据库操作的程序)
* Table Updated: // 被修改的表(此项仅对于牵扯到数据库操作的程序)
* Input: // 输入参数说明，包括每个参数的作
// 用、取值说明及参数间关系。
* Output: // 对输出参数的说明。
* Return: // 函数返回值的说明
* Others: // 其它说明
* CopyRight (c) 2023-2024 User_laubon@163.com 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 User_laubon@163.com All Right Reseverd
*/
四、注释时的注意事项
- 注释应与其描述的代码相近，对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置，不可放在下面。除非必要，不应在代码或表达中间插入注释，否则容易使代码可理解性变差。
- 变量、常量、宏的注释应放在其上方相邻位置或右方。
- 注释的内容要清楚、明了，含义准确，防止注释二义性。
- 对于所有有物理含义的变量、常量，如果其命名不是充分自注释的，在声明时都必须加以注释，说明其物理含义。
- 数据结构声明( 包括数组、结构、类、枚举等) ，如果其命名不是充分自注释的，必须加以注释。对数据结构的注释应放在其上方相邻位置，不可放在下面；对结构中的每个域的注释放在此域的右方。
- 全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明
- 注释格式尽量统一，建议使用“/* …… */”
- 注释应考虑程序易读及外观排版的因素，使用的语言若是中、英兼有的，建议多使用中文，除非能用非常流利准确的英文表达——注释语言不统一，影响程序易读性和外观排版，出于对维护人员的考虑，建议使用中文。
