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 Style进行评论。

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

输入和输出是什么。
对于班级成员函数：是否该对象记住参考超出期限的争论方法调用，以及它是否会释放他们与否。
如果函数分配内存来电者必须免费。
是否有任何参数 NULL。
如果有任何表现功能如何的含义使用
如果该功能是可重入的。什么它的同步假设是什么？

Answer 4

我坚持Visual C++ Documentation Tags MSDN推荐。我将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+也会根据How to write C++ comments that show up in Intellisense?

解释这些评论

CppTripleSlash是一款出色的免费VS插件，可在您输入＆＃34; ///＆＃34;后添加正确的XML标记。此功能从Visual Studio的C＃编辑器移植。

Answer 5

我认为没有“最好”的风格。你应该使用适合你的那个。它根据代码的用途而有很大差异。公共库API最需要这样的评论。另一方面，私有的实现类方法可能依赖于自我记录，因为没有评论通常比错误/过时的评论更好。

顺便说一句，Doxygen支持多种样式，Javadoc就是其中之一。

Answer 6

有许多评论建议，以至于它在Code Complete中有一整章。请注意，Javadocs和Doxygen风格也适用于自动生成文档。他们鼓励的通常很好。

我认为重要的一些建议是：

评论应该描述为什么，而不是你在做什么
评论应采用易于维护和输入的形式。没有幻想的ascii标题和艺术请！

Answer 7

除了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更简洁并且保持最小化。您可以查看链接以获取更多详细信息。

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

7 个答案: