C ++函数注释的最佳实践
有没有公认的评论function的最佳做法？ 我只知道doxygen风格，但它不是正式的C ++支持，就像Javadocs是Java的，所以只是想知道什么是最好的。
大多数人会同意的只有一般意见，就是评论应该说“为什么”，而不是“什么”。 除此之外，准则取决于您工作地点的编码标准。
就我个人而言，我讨厌doxygen之类的东西，因为它与我说的第一件事情相矛盾。 “文档”，如果可以这样调用的话，只是一个美化的头文件。 而成本？ 几乎重复的代码，令人反感的评论（严重的是，它将所有事物的高度加倍），只是一个痛苦。
你的代码应该是自我logging的：使用描述性的名字，把所有事情都归入明确的任务中，等等。唯一的意见应该是可能需要澄清的事情。
例如，我从一个networking套接字类的摘录中写道：
const bool socket_connected(void) const; 你已经知道这个函数做什么了， 我不需要解释它。 我真的需要添加一大块评论解释，它返回一个布尔（杜），将表明套接字连接（杜）？ 不，doxygen只是要把我的标题，并添加一些花式的样式表。
下面是一个快速注释可能有用的例子（使这个类成为可能）：
struct fancy_pants { // doesn't transfer ownship, ensure foo stays alive fancy_pants(foo&); };
现在很明显，我需要确保我通过它的foo不会超出范围。 这不需要我的代码uglification。 如果我要写文档，应该由我写，描述基本原理，预期的用法，“gotcha”，例子等。就像Boost一样。
也就是说，我所有的头文件都有一个版权块。 我觉得这是一个很棒的地方，可以写出关于这个class级的一些信息。 例如， 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); } ---------------------------------------------------------*/
它提供了一个快速演示一目了然。 更多的，就像我上面所说的，是在一个书面的文件文件。
但是你看，我大部分都是为了编写我的代码标准。 在公司，你通常不得不按照他们的标准。
没有什么会被“正式”支持，因为C ++背后没有公司。
正如你所看到的，doxygen支持很多不同的块http://www.doxygen.nl/docblocks.html
我personnaly宁愿保持接近其他reccomandations。 我尽量靠近javadoc最佳实践。
您可以按照Google风格进行评论。
在函数声明的注释中提及的事物types：
- input和输出是什么
- 对于类成员函数：对象是否会在方法调用期间记住引用参数，以及是否释放它们。
- 如果函数分配的内存，主叫方必须释放。
-
是否有任何参数可以是NULL。
-
如果有什么性能影响如何使用一个函数。
-
如果该function是可重入的。 什么是同步假设？
我会坚持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插件，可以在input“///”后添加正确的XML标签。 此function从Visual Studio的C＃编辑器移植。
有很多意见征求意见，以至于它有完整的代码完整的一章。 请注意，Javadocs和Doxygen风格也适合自动生成文档。 他们的鼓励通常很好。
一些我认为重要的build议是：
-
评论应该描述为什么，而不是你在做什么
-
评论应该以易于维护和打印的forms出现。 没有奇特的ascii标题和艺术请！
我觉得没有“最好”的风格。 你应该使用适合你的那个。 它根据代码的目的而大量变化。 公共图书馆API最需要这样的评论。 另一方面，实现类的私有方法可能可能仅仅依赖于自我logging，因为没有评论通常比错误/过时的评论更好。
顺便说一句，Doxygen支持几种风格，Javadoc就是其中之一。
除了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 */
或function代码注释：
/** 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更详细，并保持最小。 您可以查看链接了解更多详情。
