C语言注释风格
程序员文章站
2023-11-15 18:45:28
注释风格 一、前言 注释是源码程序中非常重要的一部分,一般情况下,源程序有效注释量必须在20%以上。 注释的原则是有助于对程序的阅读理解,所以注释语言必须准确、易懂、简洁,注释不宜太多也不能太少,注释的内容要清楚、明了、含义准确,防止注释二义性,该加的地方一定要加,但不必要的地方一定不要加。 注释风 ......
注释风格
一、前言
注释是源码程序中非常重要的一部分,一般情况下,源程序有效注释量必须在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; /* next item */ struct xxx_syscall syscall; /* syscall */ };
5、全局变量
全局变量要有较详细的注释,包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明。
-
description
作用描述 -
scope
作用域 -
range
取值范围 -
notice
注意事项 -
others
其他说明
/* * description: * scope: * range: * notice: * others: */