设为首页 加入收藏

TOP

C语言注释风格
2019-09-03 03:43:15 】 浏览:24
Tags:语言 注释 风格

注释风格

一、前言

注释是源码程序中非常重要的一部分,一般情况下,源程序有效注释量必须在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:
 */

C语言注释风格 https://www.cppentry.com/bencandy.php?fid=45&id=249630

】【打印繁体】【投稿】【收藏】 【推荐】【举报】【评论】 【关闭】 【返回顶部
上一篇判断一个数是否为素数 下一篇C_C语言环境、编译、预处理