C++函数注释的最佳实践

Question

评论功能是否有公认的最佳实践？我只知道doxygen风格,但C++没有正式支持它,就像Javadocs是Java一样,只是想知道什么是最好的.

Answer 1

大多数人都会同意的一般事情是,评论应该说"为什么",而不是"什么".除此之外,指南取决于您工作地点的编码标准.

就个人而言,我讨厌doxygen等,因为它与我说的第一句话相矛盾.如果可以调用"文档",它只是一个美化的头文件.和成本？几乎重复的代码,突兀的评论(严肃地说,它使一切的高度加倍),而且只是一种痛苦.

您的代码应该是自我记录的:使用描述性名称,将所有内容都纳入明确定义的任务等.唯一的注释应该是可能需要澄清的内容.

例如,我写的网络套接字类的摘录:

const bool socket_connected(void) const;

你已经知道这个功能的作用了; 我不需要解释它.我是否真的需要添加一大块注释来解释它返回一个布尔值(duh),表明套接字已连接(duh)？不,doxygen只是采取我的标题并添加一些花哨的样式表.

这是一个快速注释可能有用的例子(使这个课上升):

struct fancy_pants
{
    // doesn't transfer ownship, ensure foo stays alive
    fancy_pants(foo&);
};

现在很明显我需要确保foo我通过它不会超出范围.这不需要我的代码的uglification.如果我要编写文档,它应该由我编写,描述理由,预期用法,"陷阱",示例等.如Boost.

也就是说,我的所有标题都有一个版权块在顶部.我发现这是一个写一小部分有关课程信息的好地方.例如,is_same.hpp:

/*-------------------------------------------------------
                    <copyright notice>

Determine if two types are the same. Example:

template <typename T, typename U>
void do_something(const T&, const U&, bool flag);

template <typename T, typename U>
void do_something(const T& t, const U& u)
{
    do_something(t, u, is_same<T,U>::value);
}

---------------------------------------------------------*/

它一目了然地提供快速演示.正如我上面所说的那样,还有一个书面文档文件.

但是你看,我在大多数情况下都会制定我的代码标准.在公司,您通常必须遵循他们的标准.

Answer 2

没有任何东西会被"正式"支持,因为C++背后没有公司.

正如你所看到的,doxygen支持很多不同的块 http://www.doxygen.nl/docblocks.html

我个人更喜欢与其他其他的重新定位保持密切联系.我试着靠近javadoc最佳实践.

Answer 3

您可以按照Google样式进行评论.

在函数声明的注释中要提到的事物类型:

• 输入和输出是什么.
• 对于类成员函数:对象是否记住超出方法调用持续时间的引用参数,以及它是否将释放它们.
• 如果函数分配调用者必须释放的内存.

• 是否任何参数可以为NULL.

• 如果使用函数有任何性能影响.

• 如果该功能是可重入的.它的同步假设是什么？

Answer 4

我会坚持使用MSDN建议的Visual C ++文档标签。我将MSDN视为官方文档。

例：

/// <summary>Sorts the list to by the given column</summary>
/// <param name="sel">Column to be sorted (index-1-based) and sort direction (pos. = ascending)</param>  
/// <returns>Documentation of return type</returns>  
void CExamlist::SetSorting(int sel) { ... }

由ReSharper C ++解释为

Visual Studio 2012+还将根据如何编写Intellisense中显示的C ++注释来解释这些注释。

CppTripleSlash是一个很棒的免费VS插件，可以在您键入“ ///”后添加正确的XML标签。此功能是从Visual Studio的C＃编辑器移植的。

Answer 5

除了 Google 标准之外，我发现Edward Parrish 的这份指南非常有用！

例如块注释：

/**
    CS-11 Asn 2
    checks.cpp
    Purpose: Calculates the total of 6 checks

    @author Ed Parrish
    @version 1.1 4/10/16 
*/

或功能代码注释：

/**
    Encodes a single digit of a POSTNET "A" bar code.

    @param digit the single digit to encode.
    @return a bar code of the digit using "|" as the long
    bar and "," as the half bar.
*/

它比 doxygen 更简洁，并保持最小化。您可以查看链接以获取更多详细信息。