代码注解规范

技巧分享 , , 评论

​ 编写代码过程中自己养成写注释的好习惯，但是在不同代码中注释样式都是多种多样的，不利于阅读，经过自己长时间总结。得到下面的注解参考。

简介：

​ 注释就是对代码的解释和说明，其目的是让人们能够更加轻松地了解代码。注释是编写程序时，写程序的人给一个语句、程序段、函数等的解释或提示，能提高程序代码的可读性。注释只是为了提高可读性，不会被计算机编译。

规范确定

​ 通过自己总结与参考，得到自己的注释规范，不同的代码又小小的注释样式，单大体的注解结构不变。如果去了公司，可能就需要自己使用公司的代码规范。

头文件注释格式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
/*
 * @explain: Copyright (c) 2020 WEI.ZHOU. All rights reserved.
 * The following code is only used for learning and communication, not for illegal and commercial use.
 * If the code is used, no consent is required, but the author has nothing to do with any problems 
 * and consequences.
 * 
 * In case of code problems, feedback can be made through the following email address.
 * 					        	<xiaoandx@gmail.com>
 * 
 * @Description: 
 * @Author: author
 * @Date: 2020-11-14 08:56:42
 * @Version: V1.0
 * @Others:  Running test instructions
 */

注意： 注解关键字不区分大小写

  • 头文件的注解标签还可以加上下面两个修改人，修改时间

    1
    2
    "LastEditTime": "Do not edit",
    "LastEditors": "WEI.ZHOU",
格式用例
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
/*
 * @explain: Copyright (c) 2020 WEI.ZHOU. All rights reserved.
 * The following code is only used for learning and communication, not for
 * illegal and commercial use. If the code is used, no consent is required, but
 * the author has nothing to do with any problems and consequences.
 *
 * In case of code problems, feedback can be made through the following email address. 
 *                          <xiaoandx@gmail.com>
 *
 * @Description: 赫夫曼树定义与操作
 * @Author: WEI.ZHOU
 * @Date: 2020-11-19 16:26:10
 * @Version: V1.0
 * @Others:  Running test instructions
 *           1. 默认权重个数 4 ,修改默认参数修改宏定义中的 INIT_SIZE
 *           2. 运行代码需要先创建权重数值，不想输入创建，可将int* w; w = createWeight(); 
 *              修改为int w[INIT_SIZE];w[0]=7,w[1]=5,w[2]=2,w[3]=4;
 *           3. 修改权重编码默认样式A、B，可以修改默认参数修改宏定义中的 L_CODE、R_CODE
 *           4. 如有代码问题可以 issues <https://github.com/xiaoandx/learningCode> 
 */

函数注释格式

1
2
3
4
5
6
/**
 * @brief   
 * @Date    
 * @param   
 * @return  
 */

注意： 注解关键字不区分大小写

  • 注解标签还可以加上下面两个创建者，版本号

    1
    2
    "author": "WEI.ZHOU",
    "version": "V1.0",
格式用例
1
2
3
4
5
6
7
/**
 * @brief   获取权重的最小的下标位置
 * @Date    2020-11-19 17:25:27
 * @param   huffmanTree &hT 需要创建的赫夫曼树
 * @param   int N 权重个数
 * @return  {int} 最新权重的位置
 */

函数变量说明格式

1
2
3
4
5
/**
 * @brief 变量说明：
 * int i
 * .......
 */

注意： 变量以下说明

格式用例
1
2
3
4
5
6
/**
 * @brief 变量说明：
 * int i         for循环遍历
 * int min_one, min_two     权重数组中依次最小的两个值的位置
 * int nodeNumber       赫夫曼树的节点数
 */

规范要求

上面就是参考编码习惯确定自己的文档注解，函数注解还是变量注解，这样方便自己别人阅读自己的代码，也方便生成接口文档。

WEI.ZHOU大眼睛工程师

个人简介