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

Question

在阅读了一些关于 Doxygen 的资料之后，我有点困惑应该在哪里记录我的变量、函数等。它应该在实现文件(源文件)中还是在它的接口(interface)(头文件)中。

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

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):不要谈论如何函数做某事，只告诉什么 是的。如果您想解释实际的实现，我会在源文件中添加一些相关的(正常的)注释。