C 注释规范
c语言初学者编程规范注释
C语言初学者编程规范—注释1 注释的原则和目的注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。
通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构，使代码成为自注释的——清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释——过量的注释则是有害的。
注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码，防止没必要的重复注释信息。
示例：如下注释意义不大。
/* if receive_flag is TRUE */if (receive_flag)而如下的注释则给出了额外有用的信息。
/* if mtp receive a message from links */if (receive_flag)2 函数头部应进行注释函数头部应进行注释，列出：函数的目的/ 功能、输入参数、输出参数、返回值、调用关系(函数、表)等。
示例1：下面这段函数的注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。
/*************************************************Function: // 函数名称Description: // 函数功能、性能等的描述Calls: // 被本函数调用的函数清单Called By: // 调用本函数的函数清单Input: // 输入参数说明，包括每个参数的作// 用、取值说明及参数间关系。
Output: // 对输出参数的说明。
Return: // 函数返回值的说明Others: // 其它说明*************************************************/对于某些函数，其部分参数为传入值，而部分参数为传出值，所以对参数要详细说明该参数是入口参数，还是出口参数，对于某些意义不明确的参数还要做详细说明(例如：以角度作为参数时，要说明该角度参数是以弧度(PI),还是以度为单位),对既是入口又是出口的变量应该在入口和出口处同时标明。
c语言注释格式
c语言注释格式
在C语言中，注释可以分为单行注释和多行注释两种格式。
其中单行注释是以“//”符号开始，直到该行末尾为止，如下所示：```c
//这是一段单行注释，用于解释代码的作用及用途
```
多行注释则是以“/*”开始，以“*/”结束，可以跨越多行，如下所示：
```c
/*
这是一段多行注释，
主要用于详细说明代码的实现方法和原理
*/
```
注释应该遵循以下规范：
1. 尽量在代码段上方或对应代码行的右边添加注释，避免注释太过密集，影响代码的可读性。
2. 注释应该简洁明了，不得包含任何与代码无关的内容。
3. 注释内容应该用中文书写，确保易于理解。
4. 不得在注释中出现任何网址、超链接和电话等信息，以避免信息泄露。
通过遵循以上规范，注释可以提高代码的可读性和易维护性，为代码的编写和维护提供便利。
C 注释规范分析
C++注释规范版本：1.0制定部门：质量管理部目录1 说明 (3)2 注释种类 (3)2.1 重复代码 (3)2.2 解释代码 (3)2.3 代码标记 (3)2.4 概述代码 (3)2.5 代码意图说明 (4)2.6 传达代码无法表达的信息 (4)3 注释原则 (4)3.1 站在读者的立场编写注释 (4)3.2 注释无法取代良好的编程风格 (4)3.3 好注释能在更高抽象层次上解释我们想干什么 (5)4 规范细则 (5)4.1 文件注释规范 (5)4.2 名字空间注释规范 (6)4.3 类定义注释规范 (7)4.4 数据声明注释规范 (8)4.5 函数注释规范 (8)4.6 代码标记注释规范 (10)5 FAQ (10)5.1 枚举值需要注释吗？ (10)5.2 前置条件、后置条件和不变式有必要注释出来吗？ (10)5.3 写注释太耗时间怎么办？ (11)5.4 有效的注释是指什么？ (11)参考书目 (11)参考工具 (11)1 说明本文档用于规范C++代码中注释的编写。
规范中提出的多数注释格式都来源于文档生成工具doxygen，所以遵从本规范进行注释的C++代码都可以使用doxygen生成美观一致的代码文档。
同时另一方面，美观绝非衡量文档质量的唯一标准。
文档内容准确与否，是否充分，以及语言组织是否清晰流畅，这些都是决定一份文档质量的重要标准。
遗憾的是，这些标准当中有不少需要通过主观加以判断，很难进行明确的规范。
所以我们将尽可能的提供明确的评判标准，同时，本规范中也不可避免的提出了一些比较主观的注释要求或是建议，这些要求或是建议多数都来自于众多先驱多年的开发经验。
遵循它们不仅有助于生成一份美观的代码文档。
更重要，依照这些要求和建议来编写注释，能够有效的帮助开发者在早期就反省自己设计的合理性，同时也为编写单元测试提供更多的帮助。
2 注释种类2.1 重复代码重复性注释只是用不同文字把代码的工作又描述一次。
c语言 函数注释
c语言函数注释函数注释是编程中非常重要的一部分，它能够帮助其他开发者理解函数的作用、参数要求以及返回值等信息。
在C语言中，函数注释通常使用特定的格式进行书写，以确保注释的清晰易读。
本文将介绍C语言函数注释的格式要求以及如何编写规范的函数注释。
一、函数注释的格式要求在C语言中，函数注释通常位于函数声明之前，使用特定的注释格式进行书写。
以下是常用的函数注释格式要求：1. 函数注释以"/**"开始，以"*/"结束，中间的内容为注释的具体描述。
2. 注释的第一行为函数的摘要描述，简明扼要地说明函数的功能。
3. 注释的后续行为详细描述，可以包括函数的参数说明、返回值说明、异常情况说明等。
4. 参数说明应包括参数的名称、类型、作用、是否可以为空等信息。
5. 返回值说明应说明函数的返回值类型、返回值的作用、取值范围等信息。
6. 异常情况说明应说明函数可能出现的异常情况以及如何处理。
7. 注释中可以使用合适的标点符号、缩进、换行等方式使注释更易读。
二、编写规范的函数注释1. 函数摘要描述：函数的摘要描述应简明扼要地说明函数的功能。
例如，对于一个计算两个数之和的函数，可以使用以下方式进行摘要描述：/*** 计算两个数的和*/2. 参数说明：参数说明应包括参数的名称、类型、作用、是否可以为空等信息。
例如，对于一个计算两个数之和的函数，可以使用以下方式进行参数说明：/*** 计算两个数的和** @param num1 第一个操作数* @param num2 第二个操作数** @return 两个数的和*/3. 返回值说明：返回值说明应说明函数的返回值类型、返回值的作用、取值范围等信息。
例如，对于一个计算两个数之和的函数，可以使用以下方式进行返回值说明：/*** 计算两个数的和** @param num1 第一个操作数* @param num2 第二个操作数** @return 两个数的和* 如果计算结果超出了整型的表示范围，则返回0*/4. 异常情况说明：异常情况说明应说明函数可能出现的异常情况以及如何处理。
C++注释规范
? 如果使用第三方工具应有相关的文档及使用说明。
? 编码期间产生的调试或测试工具应有相关的说明，如果有源代码的应该提供源代码。
? 须有运行及开发环境的配置说明文档。
? 须有对文档、代码、工具文件进行说明的清单。
? 类成员变量使用m_前缀，例如int m_nItemCont;
? 全局变理使用g_前缀，例如：int g_nItemCont;
? 通用的类型缩写用为变量的前缀，指针变量在类型前缀前加上前缀p，例如：int nVariant; 其中的n代表整型，禁止使用自定义类型的缩写作为变量名前缀；char* pszVariant;其中 p表示指针,sz表示类型为0结尾的字符串类型。
? 每个分号结最多占一行。
? { 和 } 独占一行。
? 操作符之前后加一个空格
? 逗号和 ( 后面加一个空格
? 尽量不要使用指针
? 包括结构体以及数组变量等所有的变量使用前要初始化
? 内存分配遵循谁申请谁释放的原则
? 尽量使用单线程
? 所有变量初始化后再使用，变量定义集中在函数头部或类的尾部或文件的头部
*@file 文件名，存储编码格式说明（ANSI、UNICODE、UTF8等）
*@brief 概要说明
*@author 作者1姓名或者工号
*@version 版本
*@date 创建及修改日期
*@warning 警示说明（如果有的话）
*@History: 修改历史记录列表，每行修改记录应包括修改日期、修改者及修改内容简述
2.2. 命名
使用匈牙利命名法，另外：
C#文档注释规范
C#文档注释规范目录C#文档注释规范 (1)A.1. 介绍 (2)A.2.建议的标记 (3)A.2.1. <c> (4)A.2.2. <code> (5)A.2.3. <example> (5)A.2.4. <exception> (6)A.2.5. <include> (7)A.2.6. <list> (8)A.2.7. <para> (10)A.2.8. <param> (11)A.2.9. <paramref> (11)A.2.10. <permission> (12)A.2.11. <summary> (13)A.2.12. <returns> (13)A.2.13. <see> (14)A.2.14. <seealso> (15)A.2.15. <summary> (16)A.2.16. <value> (16)A.3. 处理文档文件 (17)A.3.1. ID 字符串格式 (17)A.3.2. ID 字符串示例 (18)C# 提供一种机制，使程序员可以使用含有XML 文本的特殊注释语法为他们的代码编写文档。
在源代码文件中，具有某种格式的注释可用于指导某个工具根据这些注释和它们后面的源代码元素生成XML。
使用这类语法的注释称为文档注释(documentation comment)。
这些注释后面必须紧跟用户定义类型（如类、委托或接口）或者成员（如字段、事件、属性或方法）。
XML 生成工具称作文档生成器(documentation generator)。
（此生成器可以但不一定必须是 C# 编译器本身。
）由文档生成器产生的输出称为文档文件(documentation file)。
文档文件可作为文档查看器(documentation viewer) 的输入；文档查看器是用于生成类型信息及其关联文档的某种可视化显示的工具。
c语言程序注释语句的格式是
c语言程序注释语句的格式是C语言是一种非常重要的编程语言，无论是初学者还是技术高手，都需要了解如何编写注释语句。
注释语句是一种非常有用的编程工具，可以让程序更加易于理解和维护。
下面我们来分步骤阐述C语言程序注释语句的格式：1. 单行注释在C语言中，单行注释以“//”开头，可以在一行代码的任意位置添加。
单行注释主要用来解释代码的功能或者提供开发者的个人见解。
例如：```c// 这个函数用于计算两个数的和int add(int num1, int num2){int result = num1 + num2; // 计算结果return result; // 返回结果}```2. 多行注释多行注释以“/*”开头，以“*/”结尾，可以跨越多行代码。
多行注释主要用来对程序进行详细的说明。
例如：```c/*这个程序用于计算圆的面积输入：半径（r）输出：面积（area）*/#include <stdio.h>#define PI 3.1415926 // 定义π的值int main(){float r = 5; // 定义半径float area = PI * r * r; // 计算面积printf("The area of circle is %f", area); // 输出结果return 0;}```3. 特殊注释除了单行注释和多行注释，C语言还支持一些特殊注释，包括： - 文档注释：以“/**”开头，以“*/”结尾，常用于自动生成文档。
例如：```c/*** @file main.c* @brief 首页逻辑处理程序*/```- 条件编译指令：以“#ifdef”、“#ifndef”、“#else”、“#endif”等开头，在编译时根据条件选择是否编译包含在其中的代码。
例如：```c#ifndef _MY_HEADER_H_#define _MY_HEADER_H_// 头文件内容#endif```在编写C语言注释时，我们需要遵守一些规则，以养成良好的注释习惯：- 注释的内容要具有明确的表达意义；- 注释中需要避免出现过多的语法或者代码；- 注释和代码要用空格或者制表符隔开，以增加可读性。
c语言注释格式
c语言注释格式C语言中的注释是一种重要的文本功能，可以使程序更加清晰简明。
注释可以提高代码的可读性、可维护性和可重用性，同时帮助其他程序员理解你的代码。
注释可以被编译器忽略，不会影响程序的执行，但是对于保持代码的清晰度和可读性至关重要。
下面来介绍几种常用的C语言注释格式。
1. 单行注释单行注释以“//”开头，后面跟着注释内容。
单行注释可以在代码的任意位置添加，建议将其添加在代码行的结尾。
例如：```cint main() {int a, b;a = 1; // 初始化变量ab = 2; // 初始化变量breturn a + b;}```2. 多行注释多行注释以“/*”开头，以“*/”结尾，中间包含了注释的内容。
多行注释可以跨越多个代码行，适用于对整块代码进行注释。
例如：```cint main() {/*初始化变量a和b*/int a, b;a = 1;b = 2;return a + b;}```3. 文档注释文档注释是一种特殊的注释格式，用于生成文档和API（应用程序接口）文档。
文档注释以“/*”开头，以“*/”结尾，在注释前添加一个额外的星号“*”，并在注释中使用特定的标记来描述变量、函数、参数等。
例如：```c/** @函数名称：add* @函数描述：将两个整数相加* @参数a：要相加的第一个整数* @参数b：要相加的第二个整数* @返回值：两个整数的和*/int add(int a, int b) {return a + b;}```以上是常见的C语言注释格式，注释虽然不会影响程序的执行，但是对于后续代码的阅读、维护和修改更加简便。
为了更好地体现注释的作用，程序代码中应该保持足够的注释，全面准确地描述代码的逻辑。
c语言程序注释模板
竭诚为您提供优质文档/双击可除c语言程序注释模板篇一：c语言编写规范之注释1、头文件包含includes2、私有类型定义privatetypedef3、私有定义privatedefine4、私有宏定义privatemacro5、私有变量privatevariables6、私有函数原型privatefunctionprototypes7、私有函数privatefunctions8、私有函数前注释/************************************************** ******************************Functionname:Fsmc_noR_init*description:conf igurestheFsmcandgpiostointerfacewiththenoRmemory.*thisfunctionmustbecalledbeforeanywrite/readoperation *onthenoR.*input:none*output:none*Return:none*************************************************** ****************************/9、程序块采用缩进风格编写，缩进空格为4。
10、相对独立的程序块之间、变量说明之后必须加空行；11、较长的字符（>80字符）要分成多行书写，长表达式要在低优先级操作符划分新行，操作符放在新行之首，新行要恰当缩进，保持排版整齐；12、循环、判断等语句中若有较长的表达式或语句，则要进行适应的划分，长表达式要在低优先级操作符处划分新行，操作符放在新行之首;13、若函数或过程中的参数较长，则要进行适当的划分。
14、不允许把多个短语句写在一行中，即一行只写一条语句。
15、if、for、do、while、case、switch、default等语句自占一行，且if、for、do、while等语句的执行语句部分无论多少都要加括号{}。
C注释&标签规则
1 C CODE标签和注释规约
注释要求简单，符合Doxygen文档生成规范，注释位于需要注释的上方，注释要求统一使用简洁的英文，语法方面不严格要求，但必须语义清楚明了。
1.1 新增文件标签&注释格式
2.实现文件部分(.c文件)
1.2 C代码增删改的标签和注释
1.增加代码标签和注释
进行迭代增量开发时，增加代码标签和注释格式采用如下格式：/**
@tag : begin add by 修改者名修改日期所属公司
@brief : 修改内容摘要
*/
//TODO …修改内容
/** @tag : end add by 修改者名修改日期所属公司
2.删除代码标签和注释
进行迭代增量开发时，删除代码标签和注释格式采用如下格式：
/**
@tag : begin delete by 修改者名修改日期所属公司
@brief : 删除内容摘要说明
*/
//要删除的内容，用“//”按行进行注释
//…
//…
/** @tag : end delete by 修改者名修改日期所属公司
3.修改代码标签和注释
进行迭代增量开发时，修改代码时采用先注释源代码，再增加代码，标签和注释格式采用如下格式：
/**
@tag : begin modify by 修改者名修改日期所属公司
@brief : 修改内容摘要说明
*/
//先用注释需要修改的源代码
//源代码行
增加代码
/** @tag : end modify by 修改者名修改日期所属公司。
c 语音 变量注释规则
c 语音变量注释规则
在C语言中，注释是一种用于解释代码的机制，它可以帮助程序员理解代码的功能和作用。
注释可以出现在代码的任何位置，并且可以跨越多行。
C语言中有两种类型的注释：单行注释和多行注释。
1. 单行注释：使用双斜杠（//）开头，注释的内容只能在一行中。
例如：
```c
// 这是一个单行注释
int x = 10; // 这也是一个单行注释
```
2. 多行注释：使用 / 开始，使用 / 结束。
注释的内容可以跨越多行。
例如：
```c
/ 这是一个多行注释
它可以跨越多行 /
int x = 10;
对于变量的注释，一般会遵循以下规则：
1. 在变量声明的同时进行注释，解释变量的作用和含义。
例如：
```c
// 声明一个整型变量 count，用于计数
int count = 0;
```
2. 对于复杂的变量或结构体，可以使用多行注释进行详细说明。
例如：
```c
/ 声明一个结构体 Point，表示平面上的一个点
x：点的横坐标
y：点的纵坐标 /
struct Point {
int x;
int y;
};
3. 对于常量变量，可以使用 define 预处理器指令定义，并在注释中说明其含义。
例如：
```c
// 定义一个常量 PI，表示圆周率
define PI
```
4. 在代码中使用统一的注释风格和格式，使得代码更加易读易懂。
例如，在变量声明和赋值时，可以在变量名后面添加注释，或者在变量名前面添加注释。
c语言编程规范
c语言编程规范C语言编程规范是指在使用C语言进行编程时应该遵循的一系列规定和标准。
在编写C语言程序时，遵循统一的编程规范可以提高代码的可读性、可维护性、可移植性和可靠性。
下面是一些常见的C语言编程规范，供大家参考和遵循。
1. 命名规范在C语言中，变量、函数、常量、宏等的命名应具有一定的规范性，以方便他人理解和阅读代码。
一般来说，命名应该尽量做到以下几点：- 变量和函数名使用小写字母，如果是多个单词组成，可以使用下划线 `_` 进行连接，如 `my_variable`。
- 宏常量使用全大写字母，并使用下划线 `_` 进行连接，如`MAX_SIZE`。
- 类型名和结构体名使用首字母大写的驼峰命名法，如 `MyStruct`。
- 全局变量和静态变量以 `g_` 开头，如 `g_count`。
- 局部变量使用有意义的名词或者简洁明了的单词缩写，如 `i` 表示整数变量，`ptr` 表示指针变量等。
2. 缩进与对齐在书写代码时，正确的缩进和对齐可以提高代码的可读性，让代码结构更加清晰。
通常使用4个空格进行缩进，并且在各个代码块之间使用空行进行分隔。
3. 注释规范注释是代码中必不可少的一部分，它可以解释代码的功能、逻辑和用法，便于其他人阅读和理解。
在编写注释时应尽量做到以下几点：- 使用自然语言进行注释，注释的内容要清晰明了，让其他开发人员容易理解。
- 对于复杂的逻辑或者算法，可以在代码旁边用注释进行解释。
- 对于不常见的技术或者特殊情况，可以在代码中加上注释进行说明。
- 尽量避免使用废弃的注释，及时更新和维护注释。
4. 函数规范函数是程序中的基本组成单元，编写规范的函数可以提高代码的可读性和可维护性。
在编写函数时应尽量做到以下几点：- 函数应该有明确的功能和目的，并且函数名要能够准确反映其功能。
- 函数的参数应该尽量避免过多，如果参数较多，可以考虑使用结构体传递参数。
- 函数应该尽量遵循单一职责原则，即一个函数只完成一个功能。
c,注释规范
竭诚为您提供优质文档/双击可除c,注释规范篇一：c语言编写规范之注释1、头文件包含includes2、私有类型定义privatetypedef3、私有定义privatedefine4、私有宏定义privatemacro5、私有变量privatevariables6、私有函数原型privatefunctionprototypes7、私有函数privatefunctions8、私有函数前注释/************************************************** ******************************Functionname:Fsmc_noR_init*description:configurestheFsmcandgpiostointerfacewiththenoRmemory.*thisfunctionmustbecalledbeforeanywr ite/readoperation*onthenoR.*input:none*output:none*Return:none*************************************************** ****************************/9、程序块采用缩进风格编写，缩进空格为4。
10、相对独立的程序块之间、变量说明之后必须加空行；11、较长的字符（>80字符）要分成多行书写，长表达式要在低优先级操作符划分新行，操作符放在新行之首，新行要恰当缩进，保持排版整齐；12、循环、判断等语句中若有较长的表达式或语句，则要进行适应的划分，长表达式要在低优先级操作符处划分新行，操作符放在新行之首;13、若函数或过程中的参数较长，则要进行适当的划分。
14、不允许把多个短语句写在一行中，即一行只写一条语句。
15、if、for、do、while、case、switch、default等语句自占一行，且if、for、do、while等语句的执行语句部分无论多少都要加括号{}。
c语言可用的注释符
c语言可用的注释符C语言是一种广泛使用的编程语言，它具有简单易学、高效快速等特点，因此备受程序员们的喜爱。
在C语言中，注释符是一种非常重要的语法元素，它可以帮助程序员更好地理解代码，提高代码的可读性和可维护性。
下面我们来详细了解一下C语言可用的注释符。
C语言中有两种注释符，分别是单行注释和多行注释。
单行注释以“//”开头，多行注释以“/*”开头，以“*/”结尾。
下面分别介绍一下这两种注释符的使用方法。
1. 单行注释单行注释是C语言中最常用的注释方式，它可以在一行代码的末尾添加注释，用于解释该行代码的作用。
单行注释以“//”开头，直到该行代码结束为止。
例如：```int a = 10; // 定义一个整型变量a，初始值为10```在上面的代码中，注释符“//”后面的内容“定义一个整型变量a，初始值为10”是对该行代码的解释说明，可以帮助其他程序员更好地理解代码的含义。
2. 多行注释多行注释也叫块注释，它可以注释多行代码，用于解释一段代码的作用。
多行注释以“/*”开头，以“*/”结尾，中间可以包含多行代码。
例如：```/*这是一个多行注释示例用于解释一段代码的作用*/int b = 20; // 定义一个整型变量b，初始值为20```在上面的代码中，注释符“/*”和“*/”之间的内容是对下面的代码的解释说明，可以帮助其他程序员更好地理解代码的含义。
需要注意的是，多行注释不能嵌套使用，即不能在一个多行注释中再添加另一个多行注释。
如果需要注释嵌套的代码块，可以使用单行注释或者将嵌套的代码块拆分成多个独立的代码块进行注释。
总结：C语言中的注释符是程序员编写代码时必不可少的语法元素，它可以帮助程序员更好地理解代码，提高代码的可读性和可维护性。
C语言中可用的注释符有单行注释和多行注释，分别以“//”和“/*”开头，以“*/”和“//”结尾。
程序员在编写代码时应该养成良好的注释习惯，注释应该简洁明了，不要过多地注释无关紧要的代码，以免影响代码的可读性。
CC++注释规范
CC++注释规范Doxygen是⼀种开源跨平台的，以类似JavaDoc风格描述的⽂档系统，完全⽀持C、C++、Java、和IDL语⾔，部分⽀持PHP、C#。
鉴于Doxygen良好的注释风格，故基于Doxygen以形成⾃⼰的注释规范。
1.标注总述//-------------------------------------------------------------------// Platform Defines//-------------------------------------------------------------------enum{OST_PLATFORM_WIN32 = 1,OST_PLATFORM_LINUX_X86 = 2,OST_PLATFORM_LINUX_ARM = 3,OST_PLATFORM_ANDROID = 4,OST_PLATFORM_MACOSX = 5,};//-------------------------------------------------------------------// API Export/Import Macros//-------------------------------------------------------------------/** Indicates an exported and imported shared library function. */#define OST_API_EXPORT __declspec(dllexport)#define OST_API_IMPORT __declspec(dllimport)//-------------------------------------------------------------------// Digital Image Macros//-------------------------------------------------------------------#define OST_PI 3.141592653589793f#define OST_RGB2GRAY(r, g, b) ( ((b) * 117 + (g) * 601 + (r) * 306) >> 10 )//-------------------------------------------------------------------// date and time at compile time//-------------------------------------------------------------------#define OST_TIMESTAMP __DATE__ " " __TIME__2. ⽂件头的标注/****************************************************************************** OpenST Basic tool library ** Copyright (C) 2014 Henry.Wen renhuabest@. ** ** This file is part of OST. ** ** This program is free software; you can redistribute it and/or modify ** it under the terms of the GNU General Public License version 3 as ** published by the Free Software Foundation. ** ** You should have received a copy of the GNU General Public License ** along with OST. If not, see </licenses/>. ** ** Unless required by applicable law or agreed to in writing, software ** distributed under the License is distributed on an "AS IS" BASIS, ** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. ** See the License for the specific language governing permissions and ** limitations under the License. ** ** @file Example.h ** @brief 对⽂件的简述 ** Details. ** ** @author Henry.Wen ** @email renhuabest@ ** @version 1.0.0.1(版本号) ** @date renhuabest@ ** @license GNU General Public License (GPL) ** **----------------------------------------------------------------------------** Remark : Description **----------------------------------------------------------------------------** Change History : ** <Date> | <Version> | <Author> | <Description> **----------------------------------------------------------------------------** 2014/01/24 | 1.0.0.1 | Henry.Wen | Create file **----------------------------------------------------------------------------** ******************************************************************************/3.命名空间/*** @brief 命名空间的简单概述 \n(换⾏)* 命名空间的详细概述*/namespace OST{}4. 类、结构、枚举标注/*** @brief 类的简单概述 \n(换⾏)* 类的详细概述*/class Example{};枚举类型定义、结构体类型定义注释风格类似/*** @brief 简要说明⽂字*/typedef struct 结构体名字{成员1, /*!< 简要说明⽂字 */ or ///<说明， /**<说明 */成员2, /*!< 简要说明⽂字 */ or ///<说明， /**<说明 */成员3, /*!< 简要说明⽂字 */ or ///<说明， /**<说明 */}结构体别名;5. 函数注释原则/*** @brief 函数简要说明-测试函数* @param index 参数1* @param t 参数2 @see CTest** @return 返回说明* -<em>false</em> fail* -<em>true</em> succeed*/bool Test(int index, const CTest& t);note：指定函数注意项事或重要的注解指令操作符 note格式如下： @note 简要说明 retval：指定函数返回值说明指令操作符。
C 语言注释规范
C语言注释规范版本1.0刘宝January2,2011本规范旨在对使用C语言编写的Doxygen注释统一注释风格。
1准备工作1.1中文支持DOXYFILE_ENCODING=GB2312INPUT_ENCODING=GB2312OUTPUT_LANGUAGE=Chinese1.2C语言支持OPTIMIZE_OUTPUT_FOR_C=TRUE#对C语言优化TYPEDEF_HIDES_STRUCT=TRUE#struct/union/enum使用typedef的名字HIDE_SCOPE_NAMES=TRUE#隐藏class和namespace作用域名TAB_SIZE=4#制表符占4个空格1.3额外设置根据需要选择相应设置：SOURCE_BROWSER=YES#自动加入源码INLINE_SOURCES=YES#在函数文档中嵌入对应源码REFERENCES_LINK_SOURCE=NO#把符号链接到文档REFERENCES_LINK_SOURCE=YES#把符号链接到源码2文件注释2.1样例/*!\file IMGProcess.h\author LiuBao\version 1.0\date2010/12/25\brief The brief file comment\details More details about this file,may be multi-line.*/2.2说明•“\file”后的文件名需与当前文件名一致3结构体注释3.1简洁样例typedef struct_PrimVolDesc///The brief struct comment {uint8_t PrimaryIndicator;///<The brief member commentuint8_t ISO9660Identifier[5];///<The brief member comment }PrimVolDesc;3.2详细样例/*!More details about this struct,may be multi-line.*/typedef struct_PrimVolDesc///The brief struct comment {uint8_t PrimaryIndicator;///<The brief member comment/*!More details about this member,may be multi-line.*/uint8_t ISO9660Identifier[5];///<The brief member comment }PrimVolDesc;3.3说明•“///”与注释间留有2个空格•“///<”与注释间留有1个空格•结构体成员的详细注释写在该成员上面•结构体成员的详细注释与上一成员间留1个空行•推荐结构体使用typedef类型定义•推荐使用简洁的结构体注释4枚举注释4.1样例typedef enum_COLOR///The brief enum comment{BLACK,///<The brief member commentNAVY,///<The brief member comment}COLOR;4.2说明•与结构体的简洁注释相同5宏注释5.1简洁样例#define GarbageByte0xCC///<The brief macro comment #define EndByte0xE1///<The brief macro comment ///This macro is too long,so comment here briefly!#define MALLOC(size)Mem_alloc(size,__FILE__,__LINE__)5.2详细样例/*!The detail macro comment,may be multi-line.\param a The brief parameter comment\param b The brief parameter comment\return The brief return value comment*/#define MAX(a,b)((a)>(b))?(a):(b)5.3说明•尽量少写宏函数，可以使用内联函数代替•推荐使用简洁的宏注释6函数注释6.1简洁样例/*!The detail function comment,may be multi-line.*/ void PrintAllColor();6.2详细样例/*!The detail function comment,may be multi-line.\param media The brief parameter comment\return The brief return value comment*/int CheckIMGFileSystem(media_t media);6.3说明•参数简述和返回值简述不写句号•无参无返回值的简单函数使用简洁注释•头文件有声明的函数注释在头文件中；否则注释在代码文件中7其它注释代码中其余注释一律使用普通的单行注释“//”和多行注释“/*”“*/”。
C语言注释规范
@access使用范围：class,function,var,define,module该标记用于指明关键字的存取权限：private、public或proteced@author指明作者@copyright使用范围：class，function，var，define，module，use指明版权信息@deprecated使用范围：class，function，var，define，module，constent，global，include指明不用或者废弃的关键字@example该标记用于解析一段文件内容，并将他们高亮显示。
Phpdoc会试图从该标记给的文件路径中读取文件内容@const使用范围：define用来指明php中define的常量@final使用范围：class,function,var指明关键字是一个最终的类、方法、属性，禁止派生、修改。
@filesource和example类似，只不过该标记将直接读取当前解析的php文件的内容并显示。
@global指明在此函数中引用的全局变量@ingore用于在文档中忽略指定的关键字@license相当于html标签中的<a>,首先是URL，接着是要显示的内容例如<a href=””>百度</a>可以写作 @license 百度@link类似于license但还可以通过link指到文档中的任何一个关键字@name为关键字指定一个别名。
@package使用范围：页面级别的-> define，function，include类级别的->class，var，methods用于逻辑上将一个或几个关键字分到一组。
@abstrcut说明当前类是一个抽象类@param指明一个函数的参数@return指明一个方法或函数的返回指@static指明关建字是静态的。
@var指明变量类型@version指明版本信息@todo指明应该改进或没有实现的地方@throws指明此函数可能抛出的错误异常,极其发生的情况上面提到过，普通的文档标记标记必须在每行的开头以@标记，除此之外，还有一种标记叫做inline tag,用{@}表示，具体包括以下几种：{@link}用法同@link{@source}显示一段函数或方法的内容。
c的注释符号
在C语言中，注释用于在代码中添加说明或描述，而这些注释部分在编译时会被忽略。
C语言支持两种主要类型的注释：
1. **单行注释：**
在C语言中，使用`//`来表示单行注释。
在`//`后面的所有文本都被认为是注释，直到行末。
例如：
```c
// 这是一个单行注释
int x = 5; // 这是在一行代码后的单行注释
```
2. **多行注释：**
多行注释使用`/*`开始，并使用`*/`结束。
在`/*`和`*/`之间的所有文本都被认为是注释。
这种类型的注释可以跨越多行。
例如：
```c
/*
这是一个多行注释
它可以跨越多行
*/
int y = 10;
```
注释对于代码的可读性和维护性非常重要，因为它们允许程序员添加对代码功能、目的或实现方法的解释。
C++程序注释规范
C++程序注释规范原则上注释要求使用中文;文件开始注释内容包括:公司名称、版权、作者名称、时间、模块用途、背景介绍等,复杂的算法需要加上流程说明;函数注释包括:输入、输出、函数描述、流程处理、全局变量、调用样例等,复杂的函数需要加上变量用途说明;程序中注释包括:修改时间和作者、方便理解的注释等;引用一: 文件开头的注释模板/******************************************************************** 文件名:** Copyright (c) 1998-1999 *********公司技术开发部** 创建人:** 日期:** 修改人:** 日期:** 描述:**** 版本:**-----------------------------------------------------------------------------******************************************************************/引用二: 函数开头的注释模板/***************************************************************** ** 函数名:** 输入: a,b,c** a---** b---** c---** 输出: x---** x 为1, 表示...** x 为0, 表示...** 功能描述:** 全局变量:** 调用模块:** 作者:** 日期:** 修改:** 日期:** 版本****************************************************************/ 引用三: 程序中的注释模板/*----------------------------------------------------------*//* 注释内容*//*----------------------------------------------------------*/。
- 1、下载文档前请自行甄别文档内容的完整性，平台不提供额外的编辑、内容补充、找答案等附加服务。
- 2、"仅部分预览"的文档,不可在线预览部分如存在完整性等问题,可反馈申请退款(可完整预览的文档不适用该条件!)。
- 3、如文档侵犯您的权益，请联系客服反馈,我们会尽快为您处理(人工客服工作时间：9:00-18:30)。
C++注释规范版本：1.0制定部门：技术架构部C++基础架构组2006.8目录1说明 (3)2注释种类 (3)2.1重复代码 (3)2.2解释代码 (3)2.3代码标记 (3)2.4概述代码 (3)2.5代码意图说明 (4)2.6传达代码无法表达的信息 (4)3注释原则 (4)3.1站在读者的立场编写注释 (4)3.2注释无法取代良好的编程风格 (4)3.3好注释能在更高抽象层次上解释我们想干什么 (5)4规范细则 (5)4.1文件注释规范 (5)4.2名字空间注释规范 (6)4.3类定义注释规范 (7)4.4数据声明注释规范 (8)4.5函数注释规范 (8)4.6代码标记注释规范 (10)5FAQ (10)5.1枚举值需要注释吗？ (10)5.2前置条件、后置条件和不变式有必要注释出来吗？ (10)5.3写注释太耗时间怎么办？ (11)5.4有效的注释是指什么？ (11)参考书目 (11)参考工具 (11)1说明本文档用于规范C++代码中注释的编写。
规范中提出的多数注释格式都来源于文档生成工具doxygen，所以遵从本规范进行注释的C++代码都可以使用doxygen生成美观一致的代码文档。
同时另一方面，美观绝非衡量文档质量的唯一标准。
文档内容准确与否，是否充分，以及语言组织是否清晰流畅，这些都是决定一份文档质量的重要标准。
遗憾的是，这些标准当中有不少需要通过主观加以判断，很难进行明确的规范。
所以我们将尽可能的提供明确的评判标准，同时，本规范中也不可避免的提出了一些比较主观的注释要求或是建议，这些要求或是建议多数都来自于众多先驱多年的开发经验。
遵循它们不仅有助于生成一份美观的代码文档。
更重要，依照这些要求和建议来编写注释，能够有效的帮助开发者在早期就反省自己设计的合理性，同时也为编写单元测试提供更多的帮助。
2注释种类2.1重复代码重复性注释只是用不同文字把代码的工作又描述一次。
他除了给读者增加阅读量外，没有提供更多信息。
2.2解释代码解释性注释通常用于解释复杂、敏感的代码块。
在这些场合他们能派上用场，但通常正是因为代码含混不清，才体现出这类注释的价值。
如果代码过于复杂而需要解释，最好是改进代码，而不是添加注释。
使代码清晰后再使用概述性注释或者意图性注释。
2.3代码标记标记性注释并非有意留在代码中，他提醒开发者某处的工作未做完。
在实际工作中，我们经常会使用这些注释作为程序骨架的占位符，或是已知bug的标记。
2.4概述代码概述性注释是这么做的：将若干代码行的意思以一两句话说出来。
这种注释比重复性注释强多了，因为读者读注释能比读代码更快。
概述性注释对于要修改你代码的其他人来说尤其有用。
2.5代码意图说明意图性注释用来指出要解决的问题，而非解决的方法。
意图性注释和概述性注释没有明显的界限，其差异也无足轻重，都是非常有效的注释。
2.6传达代码无法表达的信息某些信息不能通过代码来表达，但又必须包含在源代码中。
这种注释包括版权声明、作者、日期、版本号等杂项信息；与代码设计有关的注意事项；优化注记；和doxygen要求的注释等等。
3注释原则编写一份好的注释，并不比编写一段好的代码更容易，以至于我们不得不特别强调编写注释应该遵循的三个原则：3.1站在读者的立场编写注释我们的代码将会面对很多不同的读者。
其中一类是代码复审者。
他们希望看到的是准确的注释说明，小心地编写注释避免出现可笑的错误是最重要的。
接下来的读者是代码的用户，这部分人大多并不关心代码中使用了何等绝妙的高超技术。
事实上，代码能干什么，以及如何正确的使用更令他们感兴趣。
所以当我们在对那些可能面向用户的地方注释时，多多考虑一下用户的实际需要并非多余。
最后一类，怎么说呢，作为代码的维护者，他们整天要和成打的代码打交道，渴望能够用最少的时间找到目标代码。
所以，如果代码中有一些提纲挈领的注释，可以供他们用作节约代码阅读时间的索引，毫无疑问，这会令大家都工作得更加开心。
3.2注释无法取代良好的编程风格引用《代码大全》中的观点，在代码层文档中起主要作用的因素并非注释，而是良好的编程风格。
编程风格包括良好的程序结构、直率易懂的方法、有意义的变量名和函数名、具名常量、清晰的布局、以及最低复杂度的控制流及数据结构。
关于命名方面的规范参见《C++命名规范》。
虽然本篇规范讨论的重点并非编程风格，但是无论什么时候，我们都应该明白，对于精心编写的代码而言，注释不过是美丽衣裳上的小饰物而已。
3.3好注释能在更高抽象层次上解释我们想干什么在编写注释这一问题上，我们经常犯的一个错误，就是将代码已经清楚说明的东西换种说法再写一次。
尤其是如果我们为代码添加中文注释的时候，简单的等同于将英文译作中文，那么这样的注释能够给他人带来的好处微乎其微，更多时候是徒增阅读负担以及维护工作量。
再次重申，好注释不是重复代码，或是解释代码。
它们会让其意图清晰。
注释应该能在更高抽象层次上解释我们想干什么。
4规范细则4.1文件注释规范代码文件注释是典型的用于传达代码无法表达信息类的注释，所以没有太多值得讨论的地方。
一份文件注释至少需要包括以下内容：1)代码文件的文件名，占据注释的第一行并用@file加以标记2)文件内容的简要描述，占据单独一行并用@brief加以标记3)文件作者的公司email地址，占据单独一行并用@author加以标记4)文件活动年份1，占据单独一行并用@date加以标记也可以包含以下一些可选内容：1)文件内容的详细描述，紧接简要描述之后并与其以一空行隔开2)文件版本，占据单独一行并用@version加以标记，使用maj.min格式表示，其中maj为主版本号，min为次版本号。
文件注释需要放到每个代码文件的起始位置。
这里提供了一个完整的格式示例，多数情况下可以完全照搬其格式。
请注意，正如我们《C++编码规范》中提到的。
在C++世界中，我们不应该使用C风格的/*…*/块注释，而应该使用C++风格的//行注释。
是的，我们应该毫不动摇的恪守这一条1所谓“文件活动年份”，可以把它理解为文件从创建年份到最后一次维护的年份，比如2004-2006。
款。
但是，由于我们希望借助doxygen帮助我们生成漂亮的文档，如果我们在对文件注释的为了避免这样的尴尬场面，我们只好破例留下了这段C风格文件注释。
好在这是唯一必须使用C风格注释才能令doxygen满意的地方，跨过文件注释之后，我们仍然应该虔诚的遵循C++的行注释风格。
4.2名字空间注释规范名字空间是一个好东西，编写名字空间注释的要点是，不要试图把这个名字空间介绍的面面俱到。
简单的介绍设置这个名字空间的意图或是完全不要注释都是不错的选择。
如果决定要为名字空间添加注释，有一点非常重要：无论如何不要试图给同一个名字空间提供两份不同的注释，不管这些注释是否位于同一个代码文件中。
一个有效的做法是，一开始不用给名字空间添加任何注释，先用doxygen生成文档，发现哪个名字空间缺少文档，再挑选一个最合适的代码文件进行名字空间注释。
下面是一个名字空间注释的格式示例：结合前面文件注释的例子我们可以看到，@brief概述项之后，必须有一个空行用于分割随后的详细描述。
本文中所有的概述和详述项都遵循这一规则，后面将不再累述。
4.3类定义注释规范类定义注释主要有以下几个用途：∙说明该类的设计方法。
有的信息通过编码细节“逆向工程”是难以获得的，如果概述性注释能够提供这些信息，将会特别有用。
在其中应该说明类的设计思路、总体设计方法和曾考虑过后又放弃的其他方案等等。
∙类使用指南。
这主要是针对代码用户所做的注释，当看到一个类定义时，用户往往第一个念头就是想要知道这个类可以用来做什么，以及怎么才能正确地做到。
添加这样的注释，可以有效地帮助用户进入一些代码作者认为正确地使用场景，而不是任凭用户自行想象，然后使用错误的方式来操作这个类。
∙说明类不变项。
类确保从调用者的视角来看，该条件总是为真。
在类各个成员函数内部处理过程中，不变项不一定会保持，但在函数退出，控制权返回到调用者时，不变项必须为真。
请注意，要想达到以上这些目标，使用重复代码的注释方式是不可能做到的。
下面是我们一个类注释格式及演示如何达到第2、3两个个目标的例子：请特别注意例子中注释的最后部分，使用@invariant指出的不变项，这一承诺将对类所有的方法有效。
因此，单元测试的编写者将会非常乐意对这一承诺加以验证。
那么，是不是所有的类，我们都需要为其编写如此详尽细致的说明注释呢？事实上完全2@ref是doxygen中用于引用其他主题的特殊标签，本例中多处出现的引用都会指向一些方法说明。
没有必要。
所谓使用指南，只有在别人有使用的需求且存在疑问，需要这些信息加以解答时才具有实际的意义。
所以，对于大多数为了优化代码结构，或是为了实施某些设计模式而衍生出来，并不真正直接向外界提供功能的内部实现类而言，都不需要编写示例中那样太过详细的指南性质注释。
这些类更需要的是说明该类设计方法的注释。
大致上我们认为只要满足下面列举的一些条件，就应该编写较为详细的指南性说明注释：∙概要设计中明确提出的接口类∙会被多人或是多处共享的工具类∙虽是局部使用，但结构复杂以至于很容易引起错误理解以至于需要特别说明4.4数据声明注释规范数据声明包括类数据成员、具名常量和位标志。
变量声明的注释应给出变量名未表达出来的各种信息。
研究表明，对数据进行注释比对使用数据的过程做注释更为重要（SDC1982）。
下面是对数据进行注释的一些准则：∙注释数值的单位。
例如某个数值变量表示长度，请指明长度单位是英寸、英尺、米、千米还是毫米。
不能认为单位是不言自明的——新手不知道，工作于另一个系统的人也不知道。
∙说明数值的允许范围。
如果变量值有一个期望范围，就应该明确的说明这个范围。
我们约定，可以在一行以内容纳的数据声明注释，都应该使用行尾注释法，下面是一个变量声明注释的格式示例：注意///之后的<小于号，这是行尾注释必须遵循的格式。
一行无法容纳的数据声明注释，则不采用行尾注释法。
下面是一个多行注释的例子：4.5函数注释规范为一个函数编写注释，一般而言需要说明以下几个部分的信息：a)函数的概要描述，使用@brief加以标识。
注意如果一个函数无法用一两句话说清楚，就有必要考虑我们到底想让函数做什么。
要是不便做出简短的说明，往往意味着设计还嫌不足，这时就应该反思一下是否需要修正设计了。
原则上除了简单的get/set访问器，其余所有的函数都应该附上概要说明。
b)通过函数名无法传达的信息，紧接概要描述之后，并与其以一空行隔开。
如果函数名和概要描述已经足够说明这个函数的一切，那么完全可以忽略这一部分。
但有些时候我们希望告诉读者一些名称和标准功能之外的函数行为特征时，就可以将这些内容通过这种方式表达出来。