Question

关于Doxygen的一些读数后，我有点困惑在哪里记录我的变量，函数等。它应该在实现文件（源）还是在它的接口（头文件）中。

关于此的最佳做法是什么？

Answer 1

将文档放在标题中。值得注意的一件非常重要的事情就是不要过度记录。不要开始为每个变量和函数编写注释，特别是如果您所做的只是表明显而易见的。实例...

以下评论显而易见，无益。通过查看函数，所有评论都非常清楚。

/**
    This function does stuff with a prime number.  */
void do_stuff(int prime);

您应该记录该函数在极端情况下的行为方式。例如，如果参数错误，它会怎么做？如果它返回一个指针，它的职责是删除指针？程序员在使用此功能时应记住哪些其他内容？等

/**
    This function does stuff with a prime number.
    \param prime A prime number. The function must receive only primes, it
    does not check the integer it receives to be prime.
                                                                               */
void do_stuff(int prime);

另外，我建议你只在头文件中记录 interface ：不要谈论函数如何做某事，只告诉是什么< / em>确实如此。如果你想解释实际的实现，我会在源文件中添加一些相关的（正常的）注释。

Answer 2

您应该只记录您的头文件，尽管有时可能会很困难。

Answer 3

我通常建议将文档放在头文件中，并从用户角度对其进行记录。

在极少数情况下，将注释放在源文件中（甚至放在单独的文件中）可能是有益的，例如

更改标题的成本（就构建影响而言）是巨大的，
您希望（经常）更改文档，而不更改接口的语法;例如，您经常根据用户反馈改进文档，或者您有一个不同的专业作家团队，在交付界面后编写文档。

可能有其他不那么强烈的原因：有些人喜欢源代码中的注释，因为它使头文件保持小而整洁。其他人希望文档在接近实际实现的情况下更容易保持最新（存在记录函数的功能而不是如何使用它的风险）。

记录我们的C ++代码的最佳位置

3 个答案: