【发布时间】：2011-01-12 23:37:17
【问题描述】：
评论函数是否有公认的最佳实践？我只知道 doxygen 风格，但它并没有像 Javadocs 一样被 C++ 官方支持，所以只是想知道什么是最好的。
【问题讨论】：
标签： c++ coding-style comments
【发布时间】：2011-01-12 23:37:17
【问题描述】：
大多数人都会同意的一般情况是 cmets 应该说“为什么”，而不是“什么”。除此之外，指南取决于您工作地点的编码标准。
就我个人而言，我讨厌 doxygen 之类的东西，因为它与我说的第一件事相矛盾。 “文档”，如果可以这样称呼的话，只是一个美化的头文件。和费用？几乎重复的代码，突兀的 cmets（说真的，它使所有东西的高度加倍），而且只是一种痛苦。
您的代码应该是自记录的：使用描述性名称，将所有内容分解为明确定义的任务等。唯一的 cmets 应该是可能需要澄清的内容。
例如，摘自我写的一个网络套接字类：
const bool socket_connected(void) const;
你已经知道这个函数的作用了；我不需要解释。我真的需要添加一大段注释来解释它返回一个布尔值（duh），表明套接字已连接（duh）吗？不。doxygen 只是要拿走我的标题并添加一些花哨的样式表。
下面是一个快速笔记可能有用的示例（创建此类）：
struct fancy_pants
{
// doesn't transfer ownship, ensure foo stays alive
fancy_pants(foo&);
};
现在很明显，我需要确保我传递的 foo 不会超出范围。这不需要丑化我的代码。如果我要编写文档，则应该由我编写，描述基本原理、预期用途、“陷阱”、示例等。就像 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);
}
---------------------------------------------------------*/
它一目了然地提供了一个快速演示。任何其他内容，如我上面所说的，都在书面文档文件中。
但是你看，我大部分时间都在制定我的代码标准。在公司，无论如何你通常都必须遵循他们的标准。
【讨论】：
-
我讨厌将文档放入文档文件中。这意味着我有两个必须保持同步的文档。使用 doxygen 样式在标题中记录界面是我开始做的最好的事情之一。所以文档是从源代码中提取出来的。
-
@Totonga：但是，如果您被要求“增加”文档，那么您修改标题......哦，重新编译。而 doxygen cmets 的问题在于它们在很多时候是无用的：我不必阅读评论即可知道不同参数的类型和名称以及返回...那么在 cmets 中使用 5-6 行有什么意义呢？它只会浪费宝贵的屏幕空间。不要让我开始讨论内存所有权，如果我传递一个原始指针，我不希望你删除它，那是我的指针，该死的。
-
@Matthieu：Doxygen 不会强迫您记录参数/返回类型和名称 - 它可以从代码中读取这些，并且您只需要添加 cmets （如果需要注释）。当然，这并不能阻止人们添加毫无意义的样板 cmets，但他们会在有或没有 doxygen 的情况下这样做。
-
@MatthieuM。如果您有兴趣让 doxygen 远离我们宝贵的代码，请查看我已经启动的这个项目 here。您可以查看其源/输出示例on the same website
-
@Shahbaz：很好，我喜欢 reStructured（和等价的）一般，我绝对认为它们是处理文档的方式（Python 文档很棒）。
我会坚持 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? 解释这些 cmets
CppTripleSlash 是一个很棒的免费 VS 插件，可以在你输入“///”后添加正确的 XML 标签。此功能是从 Visual Studio 的 C# 编辑器移植而来的。
【讨论】：
-
就个人而言，我讨厌在 cmets 中使用 XML（等等）。是的，你为人类和计算机编写它（例如，IDE 的文档），但是，在这种情况下，XML 只是在人类可读性方面很糟糕，而且它对于解析器来说也是一个令人头疼的问题（而不是像
@param这样的东西）。呃，微软。
您可以关注Google Style 进行评论。
在函数声明中在 cmets 中提及的事物类型：
- 输入和输出是什么。
- 对于类成员函数：是否 对象记住引用 超过期限的争论 方法调用，以及是否会释放 他们与否。
- 如果函数分配内存 调用者必须释放。
任何参数是否可以 空。
如果有任何表现 函数的含义 用过。
如果函数是可重入的。什么 它的同步假设是什么？
【讨论】：
-
Google 风格反映了他们的
C方向。在C++中，如果一个参数不能是NULL，它应该是一个引用，并且内存所有权可以用智能指针在语义上表达。我不会提到谷歌的编码方式......他们在他们自己的世界里。
没有任何东西会得到“官方”支持，因为 C++ 背后没有公司。
如您所见，doxygen 支持许多不同的块。阅读：Documenting the code。
我个人更喜欢与其他建议保持密切联系。 我尽量靠近 javadoc 最佳实践。
【讨论】：
-
不同意，MSDN 官方为 cmets 提出了XML Documentation (Visual C++)。请参阅我的答案stackoverflow.com/a/42223735/433718 你的答案在 2010 年可能是正确的。
-
C++ 是官方的国际标准。不知道为什么“没有公司落后”应该是个问题。
除了 Google 标准之外，我还发现 Edward Parrish 的这份指南非常有用！
例如block cmets：
/**
CS-11 Asn 2
checks.cpp
Purpose: Calculates the total of 6 checks
@author Ed Parrish
@version 1.1 4/10/16
*/
或功能码cmets：
/**
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 更简洁，并且保持最小化。您可以查看链接了解更多详情。
【讨论】：
有很多评论建议，以至于它在Code Complete 中有一个完整的章节。请注意，Javadocs 和 Doxygen 风格也考虑到了文档的自动生成。他们鼓励的通常是好的。
我认为重要的一些建议是：
评论应该描述原因，而不是你在做什么
注释应采用易于维护和输入的形式。请不要花哨的 ascii 标题和艺术！
【讨论】：
我认为没有“最好”的风格。你应该使用适合你的那个。 它根据代码的用途而有很大差异。公共库 API 最需要这样的 cmets。另一方面，实现类的私有方法可能仅依赖于自我记录，因为没有 cmets 通常比错误/过时的 cmets 更好。
顺便说一下，Doxygen 支持多种样式，Javadoc 就是其中之一。
【讨论】：