在阅读了一些关于 Doxygen
的资料之后,我有点困惑应该在哪里记录我的变量、函数等。它应该在实现文件(源文件)中还是在它的接口(interface)(头文件)中。
关于此的最佳做法是什么。
最佳答案
将文档放在标题中。需要注意的一件非常重要的事情是不要记录过多。不要开始为每个变量和函数编写注释,尤其是当您所做的只是陈述显而易见的内容时。例子...
下面的评论很明显,但没有帮助。仅通过查看功能,所有评论都说得一清二楚。
/**
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):不要谈论如何函数做某事,只告诉什么 是的。如果您想解释实际的实现,我会在源文件中添加一些相关的(正常的)注释。
关于c++ - 记录我们的 C++ 代码的最佳位置,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/9364168/