如何编写漂亮的 C++ 注释的示例

examples of how to write beautiful c++ comments

本文关键字：注释 C++ 漂亮 何编写      更新时间：2023-10-16

也许是愚蠢的问题，但有没有办法写出好看的（短）格式为 C++ 函数、标头、变量编写注释？任何视觉示例？

这里好看是什么意思？我是这样做的..

int c;//! loop Counter
/**
 * compares (XOR) two Types
 * return boolean result
 */
bool compare(Type l, Type r);

它的 doxygen 格式。在 Comment 中有一些用于记录代码的填充格式。Doxygen是一个，另一个是naturaldocs。还有更多。这是你的味道。您甚至可能喜欢naturaldocs格式。

/*
   Function: Compare
   Compares two Types
   Parameters:
      l - lhs
      r - rhs.
   Returns:
      boolean result
*/
bool compare(Type l, Type r);

DOC++格式也更相似。

/** Comparison
    Compare two Types
    @param l Type lhs
    @param r Type rhs
    @return boolean result
*/
bool compare(Type l, Type r);

只需仅使用一种格式并坚持使用即可。

我更喜欢使用这种风格：

/**
 * Class name
 * Description
 */
class MyClass{
}

有些人会认为，最漂亮的评论是那些在整个程序中保持一致的评论。我更喜欢使用正斜杠： 

// -- short concise comments in single lines like this
// -----------------------------------------
//
//    Sectional Dividers Like This
//
// -----------------------------------------

也就是说，如果您希望从评论中生成文档，这些将无济于事。

我使用以下样式：

对于方法：

/**
 * Method description.
 * @param param1 param1 description 
 * @param param2 param2 description
 * @return return description
 * @since date since method is created
 * @author who have made this method.
 */

对于变量：

/** variables description **/

对于类：

/**
 * Class description.
 * @since date since class is created
 * @author who have made this class.
 */

最好的方法是以这样的方式进行，即某些自动化工具可以提取它们并创建交叉链接的文档。看看氧气

看看 http://www.doxygen.nl/。 基本上，JavaDoc格式的起飞，其中格式在一定程度上被解释为帮助文件。

我相信自我记录代码，但一些精通的评论会有很大帮助。

相关文章：