Doxygen注释风格

最新推荐文章于 2024-08-02 16:28:35 发布

行云_

最新推荐文章于 2024-08-02 16:28:35 发布

阅读量1.4k

点赞数 1

分类专栏：基础

本文链接：https://blog.csdn.net/wy5761/article/details/9171623

版权

基础专栏收录该内容

3 篇文章 0 订阅

订阅专栏

文件头注释

/**  	@file  [file‐name]  
  * 	@brief  brief  description  
  *		@author  <list  of  authors>  
  *  	@author  <authors  description>
  *  	@date  <date>  
  *  	@version  <version  number>  
  *  	@note  
  *  	detailed  description  
*/

函数注释（Function comments）

/**  
  *  @brief  brief  description  
  *  @author  <list  of  authors>  
  *  @param[in|out]  <parameter‐name>  <parameter  description>  
  *  @exception  <exception‐object>  <exception  description>  
  *  @return  <description  of  the  return  value>  
  *  @note  
  *  detailed  description  
  *  @remarks  <remark  text>  
*/

@param[in|out] 参数名及其解释
@exception 用来说明异常类及抛出条件
@return 对函数返回值做解释
@note 表示注解，暴露给源码阅读者的文档
@remark 表示评论，暴露给客户程序员的文档
@since 表示从那个版本起开始有了这个函数
@deprecated 引起不推荐使用的警告
@see 表示交叉参考

函数的详细注释用@note代替详细注释，因为详细注释要空行隔开，容易忘记。

变量注释

枚举变量注释

/**  Another  enum,  with  inline  docs  */  
enum  AnotherEnum  
{  
	V1,  //<  value  1  
	V2   //<  value  2  
};

全局变量

通常变量名本身就足以很好说明变量的用途，特定情况下需要额外注释说明。

// The total number of tests cases that we run through in this regression test.
const int kNumTestCases = 6;
/**  
  *  @brief  Brief  Description.  
  *  
  *  Detailed  Description  
*/  
/**<  或//<用来注释成员，放在成员后面，格式如下：  
int  var;  /**<  Detailed  description  after  the  member  */  
int  var;  ///<  Brief  description  after  the  member

类注释

/**  
  *  @class  
  *  @brief  brief  description  
  *  @author  <list  of  authors>  
  *  @note  
  *  detailed  description  
*/

实现注释（Implementation Comments）

对于实现代码中巧妙的、晦涩的、有趣的、重要的地方加于注释.

代码前注释

出彩的或复杂的代码块前要加注释，如：
// Divide result by two, taking into account that x
// contains the carry from the add.
for (int i = 0; i < result->size(); i++) {
x = (x << 8) + (*result)[i];
(*result)[i] = x >> 1;
x &= 1;
}
行注释
比较晦涩的地方要在行尾加入注释，可以在代码之后空两个空格加行尾注释。

注释原则

1. 逐层注释
为每个代码块添加注释，并在每一层使用统一的注释方法和风格。例如：
针对每个类：包括摘要信息、作者信息、以及最近修改日期等
针对每个方法：包括用途、功能、参数和返回值等
在团队工作中，采用标准化的注释尤为重要。当然，使用注释规范和工具（例如C#里的XML，Java里的Javadoc）可以更好的推动注释工作完成得更好。
2. 使用分段注释
如果有多个代码块，而每个代码块完成一个单一任务，则在每个代码块前添加一个注释来向读者说明这段代码的功能。例子如下：
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .
3. 在代码行后添加注释
如果多行代码的每行都要添加注释，则在每行代码后添加该行的注释，这将很容易理解。例如：
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
在分隔代码和注释时，有的开发者使用tab键，而另一些则使用空格键。然而由于tab键在各编辑器和IDE工具之间的表现不一致，因此最好的方法还是使用空格键。
4. 不要侮辱读者的智慧
避免以下显而易见的注释：
if (a == 5) // if a equals 5
counter = 0; // set the counter to zero
写这些无用的注释会浪费你的时间，并将转移读者对该代码细节的理解。
5. 礼貌点
避免粗鲁的注释，如：“注意，愚蠢的使用者才会输入一个负数”或“刚修复的这个问题出于最初的无能开发者之手”。这样的注释能够反映到它的作者是多么的拙劣，你也永远不知道谁将会阅读这些注释，可能是：你的老板，客户，或者是你刚才侮辱过的无能开发者。
6. 关注要点
不要写过多的需要转意且不易理解的注释。避免ASCII艺术，搞笑，诗情画意，hyperverbosity的注释。简而言之，保持注释简单直接。
7. 使用一致的注释风格
一些人坚信注释应该写到能被非编程者理解的程度。而其他的人则认为注释只要能被开发人员理解就行了。无论如何，Successful Strategies for Commenting Code已经规定和阐述了注释的一致性和针对的读者。就个人而言，我怀疑大部分非编程人员将会去阅读代码，因此注释应该是针对其他的开发者而言。
8. 使用特有的标签
在一个团队工作中工作时，为了便于与其它程序员沟通，应该采用一致的标签集进行注释。例如，在很多团队中用TODO标签表示该代码段还需要额外的工作。
int Estimate(int x, int y)
{
// TODO: implement the calculations
return 0;
}
注释标签切忌不要用于解释代码，它只是引起注意或传递信息。如果你使用这个技巧，记得追踪并确认这些信息所表示的是什么。
9. 在代码时添加注释
在写代码时就添加注释，这时在你脑海里的是清晰完整的思路。如果在代码最后再添加同样注释，它将多花费你一倍的时间。而“我没有时间写注释”，“我很忙”和“项目已经延期了”这都是不愿写注释而找的借口。一些开发者觉得应该 write comments before code，用于理清头绪。例如：
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
10. 为自己注释代码
当注释代码时，要考虑到不仅将来维护你代码的开发人员要看，而且你自己也可能要看。用Phil Haack大师的话来说就是：“一旦一行代码显示屏幕上，你也就成了这段代码的维护者”。因此，对于我们写得好（差）的注释而言，我们将是第一个受益者（受害者）。
11. 同时更新代码和注释
如果注释没有跟随代码的变化而变化，及时是正确的注释也没有用。代码和注释应该同步变化，否则这样的注释将对维护你代码的开发者带来更大的困难。使用重构工具时应特别注意，它只会自动更新代码而不会修改注释，因此应该立即停止使用重构工具。
12. 注释的黄金规则：易读的代码
对于开发者的一个基本原则就是：让你的代码为己解释。虽然有些人怀疑这会让那些不愿意写注释的开发者钻空子，不过这样的代码真的会使你容易理解，还不需要额外维护注释。例如在Fluid Interfaces文章里向你展示的代码一样：
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );
在这个例子中，注释是不需要的，否则可能就违反了技巧4。为了使代码更容易理解，你可以考虑使用适当的名字（Ottinger's Rules里讲解得相当好），确保正确的缩进，并且采用coding style guides，违背这个技巧可能的结果就像是注释在为不好的代码apologize。
13. 与同事分享技巧
虽然技巧10已经向我们表明了我们是如何从好的注释中直接受益，这些技巧将让所有开发者受益，特别是团队中一起工作的同事。因此，为了编写出更容易理解和维护的代码，尝试自由的和你的同事分享这些注释技巧。