注释风格

一、前言

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

C语言注释风格的更多相关文章

  1. C语言程序注释风格

    良好编程习惯的养成对于一个程序员的发展非常重要,而注释对于一份程序来讲又是一个必不可少的组成部分,今天来研究一下C语言程序的注释风格. 注释是源码程序中非常重要的一部分,一般情况下,源程序有效注释量必 ...

  2. go语言注释

    Go语言注释实例代码教程 - Go支持C语言风格的/* */块注释,也支持C++风格的//行注释. 当然,行注释更通用,块注释主要用于针对包的详细说明或者屏蔽大块的代码. 每个包都应有一个包注解,即 ...

  3. R 语言编码风格指南

    R 语言是一门主要用于统计计算和绘图的高级编程语言.这份 R 语言编码风格指南旨在让我们的 R代码更容易阅读.分享和检查.以下规则系与 Google 的 R 用户群体协同设计而成. 概要: R编码风格 ...

  4. 来自 Google 的 R 语言编码风格指南

    来自 Google 的 R 语言编码风格指南R 语言是一门主要用于统计计算和绘图的高级编程语言. 这份 R 语言编码风格指南旨在让我们的 R 代码更容易阅读.分享和检查. 以下规则系与 Google ...

  5. 如何在Eclipse中如何自动添加注释和自定义注释风格

    1. 如何自动添加注释 可通过如下三种方法自动添加注释: (1)输入“/**”并回车. (2)用快捷键 Alt+Shift+J(先选中某个方法.类名或变量名). (3)在右键菜单中选择“Source ...

  6. C#语言注释详解

    C#语言注释有三种形式 C#语言注释有三种形式 第一种是多行注释: /*  */ 例如: /* int a=1; int b=2; int c=3; */// 第二种是单行注释: 例如: // int ...

  7. IDEA修改XML注释风格

    作为一个强迫症患者,每次想在xml文件用快捷键注释的时候,它自动生成的注释一直都是这样的:这令我非常难受,于是每次我都要把光标移到前面,然后再Tab以下,让它变成这样可是每次都这样,好麻烦啊,如果自己 ...

  8. 个人c语言编程风格总结

    总结一下我个人的编程风格及这样做的原因吧,其实是为了给实验室写一个统一的C语言编程规范才写的.首先声明,我下面提到的编程规范,是自己给自己定的,不是c语言里面规定的. 一件事情,做成和做好中间可能隔了 ...

  9. c语言编程风格

    关于c语言的编程风格,不同的书上有不同的推荐,不同的公司有不同的要求.这里,做了一下基本规范说明. 1.变量定义 在定义变量时,前缀使用变量的类型,之后使用表现变量用途的英文单词或单词缩写,且每个单词 ...

随机推荐

  1. 实验吧——who are you?(insert into注入 二分法 时间盲注)

    题目地址:http://ctf5.shiyanbar.com/web/wonderkun/index.php 根据提示  “我要把攻击我的人都记录db中去!”  猜测这是insert into注入,会 ...

  2. 【转载】Gradle学习 第十一章:使用Gradle命令行

    转载地址:http://ask.android-studio.org/?/article/94 This chapter introduces the basics of the Gradle com ...

  3. Global variable in ABAP function group

    Function group is loaded into runtime memory by the FIRST call of a function module inside this func ...

  4. 基于RGB与HSI颜色模型的图像提取法

    现实中我们要处理的往往是RGB彩色图像.对其主要通过HSI转换.分量色差等技术来提出目标. RGB分量灰度化: RGB可以分为R.G.B三分量.当R=G=B即为灰度图像,很多时候为了方便,会直接利用某 ...

  5. 源码升级SUSE openssh

    1.check old opensslrpm -q opensslopenssl versionwhich opensslwhereis opensslls /etc/ssl 2.backup old ...

  6. Centos系统 tomcat 中的应用与北京时间相差8小时

    解决方法: 在 catalina.sh中的 JAVA_OPTS 加上 -Duser.timezone=GMT+08  启动时 startup.sh 会调用 catalina.sh.

  7. 定时调度之Quartz

    工作中我们经常碰到定时或者固定时间点去做一些事情,然后每天到时间点就会去做这样的事情,如果理解这样的场景,我们就要引入今天我们的主角Quartz,其实这个跟数据库的作业类似,但是不仅仅局限于数据库. ...

  8. Linux Tomcat安装及端口配置

    1.  JDK安装配置 待写 2. Tomcat安装配置 1,下载Tomcat链接,到启动测试. 将文件apache-tomcat-8.5.50.tar.gz移动到/usr/tomcat/下,并解压 ...

  9. 内核中dump_stack的实现原理(3) —— 内核函数printk的实现

      参考内核文档: Documentation/printk-formats.txt   在内核中使用dump_stack的时候可以看到如下用法: static inline void print_i ...

  10. 年薪30W测试工程师成长之路,你在哪个阶段?

    对任何职业而言,薪资始终都会是众多追求的重要部分.前几年的软件测试行业还是一个风口,随着不断地转行人员以及毕业的大学生疯狂地涌入软件测试行业,目前软件测试行业“缺口”已经基本饱和.当然,我说的是最基础 ...