程序中有两类注释：实现注释(implementation comments)和文档注释(document comments)。实现注释是那些在C++中见过的，使用/*...*/和//界定的注释；文档注释(被称为"doc comments")是为了让文档提取工具识别并提取的注释信息，并由/**...*/界定。文档注释可以通过doxygen工具转换成HTML文件。
实现注释用以注释代码或者实现细节。文档注释从实现自由(implementation-free)的角度描述代码的规范。它可以被那些手头没有源码的开发人员读懂。
注释应被用来给出代码的总括，并提供代码自身没有提供的附加信息。注释应该仅包含与阅读和理解程序有关的信息。例如，相应的包如何被建立或位于哪个目录下之类的信息不应包括在注释中。
在注释里，对设计决策中重要的或者不是显而易见的地方进行说明是可以的，但应避免提供代码中己清晰表达出来的重复信息。多余的注释很容易过时。通常应避免那些代码更新就可能过时的注释。
注意：频繁的注释有时反映出代码的低质量。当你觉得被迫要加注释的时候，考虑一下重写代码使其更清晰。
注释不应写在用星号或其他字符画出来的大框里。注释不应包括诸如制表符和回退符之类的特殊字符。
程序可以有4种实现注释的风格：块(block)、单行(single-line)、尾端(trailing)和行末(end-of-line)。
块注释通常用于提供对文件，方法，数据结构和算法的描述。块注释被置于每个文件的开始处以及每个方法之前。它们也可以被用于其他地方，比如方法内部。在功能和方法内部的块注释应该和它们所描述的代码具有一样的缩进格式。一般情况下，文档注释与块注释不同时出现。
块注释之首应该有一个空行，用于把块注释和代码分割开来，比如：
/*
* Here is a block comment.
*/
块注释可以以/*-开头，这样indent(1)就可以将之识别为一个代码块的开始，而不会重排它。
/*-
* Here is a block comment with some very special
* formatting that I want indent(1) to ignore.
*
* one
* two
* three
*/
注意：如果你不使用indent(1)，就不必在代码中使用/*-，或为他人可能对你的代码运行indent(1)作让步。
参见"文档注释"
短注释可以显示在一行内，并与其后的代码具有一样的缩进层级。如果一个注释不能在一行内写完，就该采用块注释(参见"块注释")。单行注释之前应该有一个空行。以下是一个Java代码中单行注释的例子：
if (condition) {
/* Handle the condition. */
...
}
极短的注释可以与它们所要描述的代码位于同一行，但是应该有足够的空白来分开代码和注释。若有多个短注释出现于大段代码中，它们应该具有相同的缩进。
以下是一个Java代码中尾端注释的例子：
if (a == 2) {
return TRUE; /* special case */
}
else {
return isPrime(a); /* works only for odd a */
}
文档注释是为专用的文档生成工具（这里使用doxygen）使用的标志，主要用于生成完整的API说明文档。
说明性注释一般出现在说明性文件中，集中说明整个文件的作用。
说明性文件（如头文件.h文件、.inc文件、.def文件、编译说明文件.cfg等）头部应进行注释，注释必须列出：版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系.
示例：下面这段头文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。
/*!
* @attention Copyright (C), 2004-2006, REPACE Center, SEI, Xidian
* University.
*
* @file file.h // 文件名
* @author David // 作者名称
* @version 1.0
* @date 06/08/13
*
* @brief // 用于详细说明此程序文件完成的主要功能，与其他模块
* // 或函数的接口，输出值、取值范围、含义及参数间的控* // 制、顺序、独立或依赖等关系
*
* @brief // 其它内容的说明
*
*/
源文件头部应进行注释，列出：版权说明、版本号、生成日期、作者、模块目的/功能。
示例：下面这段源文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。
/*!
* @attention Copyright (C), 2004-2006, REPACE Center, SEI, Xidian
* University.
*
* @file file.cpp // 文件名
* @author David // 作者名称
* @date 06/08/13
* @brief // 模块描述
* @version 1.0
*/
说明：模块描述一项描述本文件的内容、功能、内部各部分之间的关系及本文件与其它文件关系等。
接口注释是指二次开发人员所使用的关键函数或类进行的说明性文字，采用文档生成工具生成说明文档。
函数头部应进行注释，列出：函数的目的/功能、输入参数、输出参数、返回值等。
示例：下面这段函数的注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。
/*!
* @fn bool memcpy(void *dest, const void *src, size_t n)// 函数名称
* @brief 内存拷贝函数 // 函数功能、性能等
* @param[out] dest The memory area to copy to. //参数描述
* @param[in] src The memory area to copy from.
* @param[in] n The number of bytes to copy.
* @return bool for success or not. //返回值
*
* @attention 注意事项
* @warning 一些使用函数需要引起严重后果的警告信息
* @bug 记录该函数的bug
*
* @attention 以下为修改记录
*
* @attention 修改记录1
* @author mask
* @date 06/08/13
* @version 1.0
* @attention 修改了函数的第一个参数，由原来的int改为char类型
*
* @attention 修改记录2
* @author David
* @date 06/08/15
* @version 1.01
* @attention 修改了函数的第一个参数，由原来的int改为char类型
*/
bool memcpy(void *dest, const void *src, size_t n);
修改历史记录列表中每条修改记录应包括修改日期、修改者及修改内容简述。
/*!
* @class WindowsNT
* @brief Windows Nice Try.
* @author Bill Gates
* @author Several species of small furry animals gathered together
* in a cave and grooving with a pict.
* @version 4.0
* @date 1996-1998
*/
class WindowsNT {};
变量注释包含：变量类型、变量名称和作用三个部分
/*!
* @var int speed
* @brief 物体的运行速度
*/
int speed;
本文来源：https://www.2haoxitong.net/k/doc/a5cffd7b31b765ce050814e5.html
文档为doc格式