【C语言基础】编程规范——注释
1、头文件的头部注释
/**
* Copyright (C), 2020-2020, github.com/XIN-Mr.
* File name: test.h // 文件名
* Author:XIN-Mr Version:V1.0 Date:2020.8.5 // 作者、版本及完成日期
* Description: // 用于详细说明此程序文件完成的主要功能，与其他模块
// 或函数的接口，输出值、取值范围、含义及参数间的控
// 制、顺序、独立或依赖等关系
* Others: // 其它内容的说明
* Function List: // 主要函数列表，每条记录应包括函数名及功能简要说明
1. ....
* History: // 修改历史记录列表，每条修改记录应包括修改日期、修改
// 者及修改内容简述
1. Date:
Author:
Modification:
2. ...
*//*!
* @file LQ_ADC.c
*
* @brief ADC驱动文件
*
* @company
*
* @author XIN-Mr
*
* @note 无
*
* @version V1.1 2019/12/06 优化注释 Doxygen
*
* @par URL http://shop36265907.taobao.com
* http://www.lqist.cn
*
* @date 2020/8/7 星期五
*/
2、源文件的头部注释
/**
* Copyright (C), 2020-2020, github.com/XIN-Mr.
* FileName: test.c
* Author:XIN-Mr Version :V1.0 Date:2020.8.5
* Description: // 模块描述
* Version:该版本主要测试了···// 版本信息
* Function List: // 主要函数及其功能
1. -------
* History: // 历史修改记录
3、源文件函数的头部注释
/**
* Function: // 函数名称
* Description: // 函数功能、性能等的描述
* Calls: // 被本函数调用的函数清单
* Called By: // 调用本函数的函数清单
* Table Accessed: // 被访问的表(此项仅对于牵扯到数据库操作的程序)
* Table Updated: // 被修改的表(此项仅对于牵扯到数据库操作的程序)
* Input: // 输入参数说明，包括每个参数的作
// 用、取值说明及参数间关系。
* Output: // 对输出参数的说明。
* Return: // 函数返回值的说明
* Others: // 其它说明
*/
/*!
* @brief ADC通道初始化
*
* @param channel ： ADC通道 LQ_ADC.h中的一个枚举体
* @param bit ： ADC通道精度 LQ_ADC.h中的一个枚举体
*
* @return 无
*
* @note 读取ADC之前一定要调用该函数对ADC通道进行初始化
*
* @see ADC_InitConfig(ADC0CH0_P0_10, ADC_12bit); //初始化ADC通道0 P0_10
*
* @date 2019/10/21 星期一
*/
void ADC_InitConfig(ADCn_Ch channel, ADC_nbit bit)
{
}
4、其他注释
代码行上方 /****balabala****/注释
代码行右方 /****balabala****/ 或 // balabala 注释
一、宏定义
/*! CTIMER 最大占空比 可自行修改 */
#define CMTER_PWM_MAX 10000二、结构体、枚举体注释
/**
* @brief CTIMER模块 脉冲计数通道
* @note CTIMER 模块 脉冲捕获通道
* @note CTIMER 模块的输入管脚并不是直接CTIMER连接的 而是通过INPUTMUX模块连接的
* @note CTIMER计数器 --- INPUTMUX输入多路复用模块17路通道 ---- 芯片外部管脚
* @note 简单说 就是CTIMER的捕获通道每个都可以与 INPUTMUX模块的17路通道相链接
* @note INPUTMUX模块的17路通道相链接的管脚如下
*/
typedef enum
{
CTInput0_P0_1 = 0x0000 + 1, CTInput0_P0_13 = 0x0000 + 2, /*!< INPUTMUX—CTIMER 输入通道0管脚 */
CTInput1_P0_14 = 0x0100 + 1, CTInput1_P0_2 = 0x0100 + 2, /*!< INPUTMUX—CTIMER 输入通道1管脚 */
CTInput2_P1_0 = 0x0200 + 1, CTInput2_P1_28 = 0x0200 + 2, /*!< INPUTMUX—CTIMER 输入通道2管脚 */
CTInput3_P1_1 = 0x0300 + 1, CTInput3_P1_26 = 0x0300 + 2, /*!< INPUTMUX—CTIMER 输入通道3管脚 */
CTInput4_P1_9 = 0x0400 + 1, CTInput4_P0_16 = 0x0400 + 2, /*!< INPUTMUX—CTIMER 输入通道4管脚 */
CTInput5_P1_11 = 0x0500 + 1, /*!< INPUTMUX—CTIMER 输入通道5管脚 */
CTInput6_P1_13 = 0x0600 + 1, /*!< INPUTMUX—CTIMER 输入通道6管脚 */
CTInput7_P1_15 = 0x0700 + 1, /*!< INPUTMUX—CTIMER 输入通道7管脚 */
CTInput8_P0_24 = 0x0800 + 1, /*!< INPUTMUX—CTIMER 输入通道8管脚 */
CTInput9_P0_25 = 0x0900 + 1, /*!< INPUTMUX—CTIMER 输入通道9管脚 */
CTInput10_P0_10= 0x0A00 + 1, /*!< INPUTMUX—CTIMER 输入通道10管脚 */
CTInput11_P0_28= 0x0B00 + 1, /*!< INPUTMUX—CTIMER 输入通道11管脚 */
CTInput12_P0_4 = 0x0C00 + 1, /*!< INPUTMUX—CTIMER 输入通道12管脚 */
CTInput13_P0_6 = 0x0D00 + 1, /*!< INPUTMUX—CTIMER 输入通道13管脚 */
CTInput14_P1_20= 0x0E00 + 1, CTInput14_P0_26= 0x0E00 + 2, /*!< INPUTMUX—CTIMER 输入通道14管脚 */
CTInput15_P0_20= 0x0F00 + 1, CTInput15_P0_22= 0x0F00 + 2, /*!< INPUTMUX—CTIMER 输入通道15管脚 */
CTInput16_P0_15= 0x1000 + 1, /*!< INPUTMUX—CTIMER 输入通道16管脚 */
} CTIMER_InputChannel_t;
三、全局变量
/** DMA link传输描述符 */
extern dma_descriptor_t s_dma_descriptor_table0[];变量作用域的前缀：
/** 全局变量 */
uint32_t g_ulParaWord;
/** 静态变量 */
static uint32_t s_ulParaWord;
附：软件中常用的正反义词组命名。
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