注释风格
一、前言
注释是源码程序中非常重要的一部分，一般情况下，源程序有效注释量必须在20%以上。
注释的原则是有助于对程序的阅读理解，所以注释语言必须准确、易懂、简洁，注释不宜太多也不能太少，注释的内容要清楚、明了、含义准确，防止注释二义性，该加的地方一定要加，但不必要的地方一定不要加。
注释风格很多，这里只是对于我的代码进行规范。
二、风格
1、文件注释
FileName文件名Description模块描述Change Logs变更日志
/*
* Copyright (C), 1988-1999, Xxxxxx Tech. Co., Ltd.
* FileName: xxx
* Description: balabalabalabalabalabalabalabalabala
balabalabalabalabalabalabalabalabalabalabalabala
* Change Logs:
|Date |Author |Notes |version
|2010-03-22 |XXX |XXX |1.0.0
*/
2、函数注释
Function函数名称Description函数描述Calls调用的函数清单Input输入参数说明，包括每个参数的作用、取值说明及参数间关系Output输出参数的说明Return函数返回值的说明Others其他说明
/*
* Function:
* Description:
* Calls:
* Input:
* Input:
* Output:
* Return:
* Others:
*/
3、宏定义注释
@define定义块概述No error定义值说明
/* @define xxx */
#define XXX_ERROR_OK 0 /* No error */
#define XXX_ERROR_INVALID_TOKEN 1 /* Invalid token */
#define XXX_ERROR_EXPECT_TYPE 2 /* Expect a type */
4、结构体注释
@struct结构体概述next item结构体元素说明
/* @struct xxx */
struct xxx_syscall_item
{
struct xxx_syscall_item* next; /* 下一个item */
struct xxx_syscall syscall; /* syscall */
};
5、全局变量
全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明。
Description作用描述Scope作用域Range取值范围Notice注意事项Others其他说明
/* @variable temp */
/* Scope: 存储温度值 */
/* Range: -128 - 127 */
/* Notice: xxxxx */
/* Others: xxxxx */
extern char temp = 0;