C++ 函数注释的最佳实践
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/2198241/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Best practice for C++ function commenting
提问by 1337
Is there an accepted best practice for commenting functions? I only know of the doxygen style but it is not officially supported by C++ like Javadocs is for Java so just wondering what is best.
是否有评论功能的公认最佳实践？我只知道 doxygen 风格，但它不受 C++ 的正式支持，就像 Javadocs 适用于 Java，所以只是想知道什么是最好的。
回答by GManNickG
There only general thing most people will agree with is that comments should say "why", not "what". Other than that, guidelines depend on the coding standards at your place of work.
大多数人会同意的唯一普遍的事情是评论应该说“为什么”，而不是“什么”。除此之外，指南取决于您工作场所的编码标准。
Personally, I hate doxygen and the like, because it contradicts the first thing I said. The "documentation", if it can be called that, is just a prettified header file. And the cost? Nearly duplicated code, obtrusive comments (seriously, it doubles the height of everything), and just a pain.
就我个人而言，我讨厌 doxygen 之类的东西，因为它与我说的第一件事相矛盾。“文档”，如果可以这样称呼的话，只是一个美化的头文件。以及费用？几乎重复的代码，突兀的注释（严重的是，它使所有内容的高度增加了一倍），而且只是一种痛苦。
Your code should be self-documenting: use descriptive names, factor everything into well-defined tasks, etc. The only comments should be things that may need clarification.
您的代码应该是自文档化的：使用描述性名称，将所有内容都纳入明确定义的任务中，等等。唯一的注释应该是可能需要澄清的内容。
For example, an excerpt from a network socket class I wrote:
例如，我写的网络套接字类的摘录：
const bool socket_connected(void) const;
You already know what this function does; I don't need to explain it. Do I really need to add a big chunk of comment explaining that it returns a boolean (duh) that will indicate of the socket is connected (duh)? No. doxygen is just going to take my header and add some fancy style-sheet to it.
你已经知道这个函数的作用了；我不需要解释。我真的需要添加一大块注释来解释它返回一个布尔值 (duh) 来指示套接字已连接 (duh)？不。doxygen 只是要拿我的标题并添加一些花哨的样式表。
Here's an example where a quick note may be useful (making this class up):
这是一个快速笔记可能有用的示例（组成这个类）：
struct fancy_pants
{
// doesn't transfer ownship, ensure foo stays alive
fancy_pants(foo&);
};
Now it's clear I need to make sure the fooI pass it doesn't go out of scope. This didn't require the uglification of my code. If I'm going to write documentation, it should be written by me, describing rationale, intended usage, "gotcha"'s , examples, etc. Like Boost.
现在很明显我需要确保foo我通过它不会超出范围。这不需要丑化我的代码。如果我要写文档，它应该是我写的，描述基本原理、预期用途、“陷阱”、示例等。比如 Boost。
That said, all my headers have a copyright block on the top. I find this is a fantastic place to write a tiny bit of info about the class. For example, is_same.hpp:
也就是说，我所有的标题顶部都有一个版权块。我发现这是一个写关于班级信息的好地方。例如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);
}
---------------------------------------------------------*/
It gives a quick demo at a glance. Anything more, like what I said above, is in a written documentation file.
它提供了一个一目了然的快速演示。任何更多，就像我上面所说的，都在书面文档文件中。
But you see, I get to make up my code standards for the most part. At companies, you usually have to follow their standard anyway.
但是你看，我大部分时间都在制定我的代码标准。在公司，无论如何你通常都必须遵循他们的标准。
回答by OneWorld
I'd stick to the Visual C++ Documentation TagsMSDN recommends. I see MSDN as the official documentation.
我会坚持使用MSDN 推荐的Visual C++ 文档标签。我将 MSDN 视为官方文档。
Example:
例子：
/// <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) { ... }
Gets interpreted by ReSharper C++ to
由 ReSharper C++ 解释为
Visual Studio 2012+ will interpret those comments as well according to How to write C++ comments that show up in Intellisense?
Visual Studio 2012+ 也将根据如何编写出现在 Intellisense 中的 C++ 注释来解释这些注释？
CppTripleSlashis a great free VS plugin that adds the correct XML tags after you type "///". This feature is ported from Visual Studio's C# editor.
CppTripleSlash是一个很棒的免费 VS 插件，它会在您键入“///”后添加正确的 XML 标签。此功能是从 Visual Studio 的 C# 编辑器移植的。
回答by codaddict
You can follow the Google Stylefor commenting.
您可以按照Google Style进行评论。
Types of things to mention in comments at the function declaration:
在函数声明的注释中提及的事情类型：
- What the inputs and outputs are.
- For class member functions: whether the object remembers reference arguments beyond the duration of the method call, and whether it will free them or not.
- If the function allocates memory that the caller must free.
Whether any of the arguments can be NULL.
If there are any performance implications of how a function is used.
If the function is re-entrant. What are its synchronization assumptions?
- 输入和输出是什么。
- 对于类成员函数：对象是否在方法调用持续时间之后记住引用参数，以及它是否会释放它们。
- 如果函数分配了调用者必须释放的内存。
是否有任何参数可以为 NULL。
如果对函数的使用方式有任何性能影响。
如果函数是可重入的。它的同步假设是什么？
回答by X-Blaster
Nothing will be "officially" supported because there's no company behind C++.
什么都不会得到“官方”支持，因为 C++ 背后没有公司。
As you can see, doxygen support a lot of different blocks http://www.doxygen.nl/docblocks.html
如您所见，doxygen 支持很多不同的块 http://www.doxygen.nl/docblocks.html
I personnaly prefer to stay close to other other reccomandations. I try to stay near javadoc best practices.
我个人更喜欢靠近其他其他推荐。我尽量接近 javadoc 最佳实践。
回答by BugShotGG
Apart from Google Standards I found this guide here by Edward Parrishto be very useful!
除了 Google 标准之外，我发现Edward Parrish 的这份指南非常有用！
For example block comments:
例如块注释：
/**
CS-11 Asn 2
checks.cpp
Purpose: Calculates the total of 6 checks
@author Ed Parrish
@version 1.1 4/10/16
*/
or function code comments:
或功能代码注释：
/**
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.
*/
Its less verbose than doxygen and keeps it minimal. You can check the link for further details.
它比 doxygen 更简洁，并保持最小化。您可以查看链接以获取更多详细信息。
回答by Extrakun
There are number of advice for commenting, so much so that it has an entire chapter in Code Complete. Do note that Javadocs and Doxygen style are also catering to automatic generation of documentation in mind. What they encouraged is usually fine.
有许多评论建议，以至于它在Code Complete 中有一整章。请注意，Javadocs 和 Doxygen 风格也考虑到了文档的自动生成。他们鼓励的通常是好的。
Some advice which I find important are:
我认为重要的一些建议是：
Comments should describe why, not what you are doing
Comments should be in a form easy to maintain and type out. No fanciful ascii header and art please!
评论应该描述原因，而不是你在做什么
评论应该采用易于维护和输入的形式。请不要幻想的 ascii 标题和艺术！
回答by Alex Jenter
I think there is no such thing as the "best" style. You should use the one that works for you. It varies heavily based on the purpose of the code. Public library APIs need such comments the most. On the other hand, private methods of implementation classes may probably rely on just being self-documenting, as no comments is usually better than wrong/obsolete comments.
我认为没有所谓的“最佳”风格。你应该使用适合你的那个。它根据代码的目的而有很大差异。公共库 API 最需要这样的注释。另一方面，实现类的私有方法可能只依赖于自我记录，因为没有注释通常比错误/过时的注释更好。
By the way, Doxygen supports several styles, Javadoc being one of them.
顺便说一下，Doxygen 支持多种风格，Javadoc 就是其中之一。
