最佳实践:在C/C++代码中，函数注释应该放在哪里？
最佳实践:在C/C++代码中，函数注释应该放在哪里？
提问于 2009-12-05 06:12:31
所以..。我理解这可能是主观的，但我想要一些关于这方面的最佳实践的意见。
假设我有以下头文件和.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文件中函数声明上方或函数定义上方的头部中？谢谢，所以
回答 14
Stack Overflow用户
回答已采纳
发布于 2009-12-05 06:14:40
我在头文件中添加了描述函数功能的注释，并在cpp文件中添加了注释来描述它是如何做到这一点的。
Stack Overflow用户
发布于 2009-12-05 06:15:20
我倾向于在头文件中使用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文件，该文件将注释它是如何实现其目标的。
Stack Overflow用户
发布于 2009-12-05 08:03:39
按重要性排序：
- 如果它是现有项目的一部分，并且有一种流行的注释样式，请使用该样式。代码库中的一致性比单个开发人员的偏好更重要。
- 如果这是一个新项目，请使用Doxygen或类似的工具来记录代码。尽管这并不能回答你的问题，因为你可以同时使用这两种风格。每晚运行它，这样你就有了最新的可浏览的源代码documentation.
- Personally，我更喜欢在头文件中只放一行简短的内联函数和成员摘要，否则在浏览头文件时很难获得类功能的简要概述。详细的描述留在.cpp文件中。有些访问器我不会评论它们的目的是否真的很明显。
我对懒惰的评论也有很大的不满，特别是一行：
例如，这条评论是浪费空间，不妨删除：
/** Get the width */
double getWidth();这条评论很有用：
/** Get the width in inches excluding any margin. */
double getWidth();页面原文内容由Stack Overflow提供。腾讯云小微IT领域专用引擎提供翻译支持
原文链接：
https://stackoverflow.com/questions/1849991
复制相关文章
相似问题
腾讯云开发者
