Question

所以...我明白这可能是主观的，但我想就这方面的最佳做法提出一些意见。

说我有以下标题和.cpp文件：

标题

// foo.h

class foo
{
public:
    int bar(int in);
};

CPP：

// foo.cpp

int foo::bar(int in)
{
    // some algorithm here which modifies in and returns the modified value
}

现在说我有这个功能评论：

/* 
    input:    an integer as input to algorithm foo

    output:   The result of the algorithm foo on input in

    remarks:  This function solves P = NP
*/

最佳做法是将此函数注释放在函数声明上方的标题中还是cpp文件中函数定义的上方？谢谢你

Answer 1

我在头文件中描述了描述函数所做的的注释以及在cpp文件中描述如何的注释。

Answer 2

我倾向于在头文件中使用doxygen的格式作为函数注释，允许窥视的程序员学习更多内容。

/**
 * Fills the handler with GIF information
 * 
 * @param filename GIF File name to be loaded
 * @return Inited GIF Handler or NULL for error
 */
pGifHandler gifHandlerLoad(const char* filename);

/**
 * Removes all data used by the GIF handler
 * 
 * @param gifHandler GIF Handler to be destroyed
 * @note This also clears palette and bitmap(s)
 */
void gifHandlerDestroy(pGifHandler gifHandler);

想要知道某个功能如何使其工作的程序员应该查看.cpp文件，该文件将就如何实现它的目标发表评论。

Answer 3

按重要性排序：

如果它是现有项目的一部分并且存在流行的评论风格，请使用它。代码库中的一致性比单个开发人员的首选项更重要。
如果是新项目，请使用Doxygen或类似文件来记录您的代码。虽然这不能回答你的问题，因为你可以使用它们的两种风格。每晚运行它，以便您拥有最新的可浏览源文档。
就个人而言，我更喜欢只在头文件中添加简短的内联函数和成员的一行摘要，否则在浏览头文件时会更难以简要概述类的功能。。我留给.cpp文件的详细说明。一些访问者如果他们的目的非常明显，我不予置评。

对于懒惰的评论，我也有很大的烦恼，特别是单行：

e.g。这个评论是浪费空间，也可能被删除：

/** Get the width */
double getWidth();

此评论很有用：

/** Get the width in inches excluding any margin. */
double getWidth();

Answer 4

我个人更喜欢把它放在实现之上。我也使用Doxygen样式，因为它提供相同的信息，但生成文档。

但这并不重要，特别是如果你继续使用doxygen构建单独的文档。按照你的喜好去做。

Answer 5

将注释放在标题中是一种更好的解决方案。这是因为：

在寻找文档时一个函数，标题是第一个检查的地方。
源文件可能无法使用。
源文件包含更多内容比功能声明，和有用的评论可能会被淹死。

Answer 6

我使用Doxygen并在标题中使用简短的单行描述，并在实现文件中使用强大的多行描述。我认为这会产生更清晰的头文件，这对我来说更容易。

注意：如果您将此代码作为库发布，那么人们可能不想深入了解实现。但是，头文件通常是公平的游戏。在这种情况下，我会在标题中放入详细的文档。

头：

// foo.h

class foo
{
public:
    /**\brief This function solves P = NP */
    int bar(int in);
};

CPP：

// foo.cpp

/** 
 \param[in]    an integer as input to algorithm foo

 \returns    The result of the algorithm foo on input in
*/
int foo::bar(int in)
{
    // some algorithm here which modifies in and returns the modified value
}

Answer 7

将函数注释放在头文件中。（除了手册之外）是您班级用户寻找文档的第一个地方。他们不关心实现，只关心接口。

Answer 8

我喜欢使用PRE / POST条件。所提到的答案都没有错。你/公司更喜欢什么？但PRE和POST条件告诉您传入/传出变量是什么以及如何使用它们。它还确保您遵循某种关于如何调用函数的指导原则（前置条件）以及此函数后的输出量（后置条件）。

Answer 9

一般来说，评论应该以类似于代码分离的方式处理 - interface 相关的评论（例如你的例子）将放在标题中，而实现相关的注释更适合.cpp文件。

如果有人将您的类包含在他们自己的程序中，他们应该能够从头文件中获取足够的信息，以了解如何使用该类而不必闯入实现本身。超出这个标题的评论可能是不必要的，只会使有用的信息混乱。

Answer 10

这就像询问穿袜子的最佳做法是什么。如果你把声明和评论放在一起，有些工具有更好的工作机会，这可能对人们的期望最有意义。但是随意评论是毫无意义的。特别是进/出东西，除非你有一个使用它的工具。任何程序员都可以从声明中看到他或她需要什么，这同样适用于语言。没有什么比像//这是构造函数的评论更无用了。

而是尝试保持代码本身尽可能简单，使用有意义的名称和代码的一般组织，如果有任何奇怪的内容，请写一个关于它的真实段落 //我们必须这样做，因为我们使用的一些奇怪的api需要某些东西 //导致其他一些事情破坏，并且有时会调用它 //所以不要取出这些方法调用或优化器优化 //其他一些东西，整个程序停止工作

Answer 11

标题中的目的，合同上面的函数实现，为什么在函数体中。

要求提供.cpp，或使用doxygen之类的工具发布文档。

依赖关系中的优势：改进文档不会影响标头依赖性。

无论如何，选择一种风格，并保持一致

Answer 12

最佳实践是编写代码的组织的标准。

如果只是为了我：

标题中的功能目的和用法，实现中的功能细节。

Answer 13

因为我一直使用Visual Assist X，并且能够非常容易地跳转代码，所以我使用头文件作为索引。也就是说，头文件仅包含没有附加注释的相关数据，因为不向文件添加膨胀。如果读者想要有关该功能的更多信息，他们可以跳转到cpp。

这当然假设读取您代码的所有人都具有相同的思维过程，这是错误的。虽然只在一个文件中有膨胀是很好的。

Answer 14

在函数内部，您可以将注释放在与左括号相同的行上。


/* what is this function for, and so on.  Stuff the caller needs to know. */
foo ()
{       // pre-condition
}

我已经看到推荐作为列出前置条件的位置。我试过了，发现它相当狭窄，因为我倾向于写冗长的评论。此外，前置条件是调用者需要注意的事情，它不应该在函数体内丢失。

否则，我总是尝试将函数的整体描述放在它之外，并解释为什么它在代码旁边的函数内部编码。所以大体上同意Doxygen推动者的风格。

最佳实践：函数注释应该放在C / C ++代码中的哪个位置？

14 个答案: