Question

也许是一个愚蠢的问题，但有没有办法写好看（短）格式写c ++函数，标题，变量的注释？任何视觉例子？

Answer 1

在这里好看，你是什么意思？我这样做..

int c;//! loop Counter

/**
 * compares (XOR) two Types
 * return boolean result
 */
bool compare(Type l, Type r);

它的doxygen格式。有一些populer格式用于在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);

只使用一种格式并坚持下去。

Answer 2

我更喜欢使用这种风格：

/**
 * Class name
 * Description
 */

class MyClass{

}

Answer 3

有人会建议最美丽的评论是整个课程中一致的评论。我更喜欢使用正斜杠：

// -- short concise comments in single lines like this

// -----------------------------------------
//
//    Sectional Dividers Like This
//
// -----------------------------------------

尽管如此，如果您希望从您的评论中生成文档，这些将无济于事。

Answer 4

最好的方法是以某种自动化工具可以提取它们并创建交叉链接文档的方式来实现。看看doxygen

Answer 5

我使用以下风格：

方法：

/**
 * 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.
 */

Answer 6

看看http://www.doxygen.nl/。基本上，对于帮助文件，在某种程度上解释格式的JavaDoc格式的起飞。

我是自我记录代码的信徒，但一些精通的评论可以提供很多帮助。

如何编写漂亮的c ++注释的例子

6 个答案: