【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:         // 历史修改记录

              

      David    96/10/12     1.0     build this moudle

 */

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