<分区>
这是一个非常简单的问题，令我惊讶的是我在 SO 上没有找到其他任何地方。我想知道哪些注释应该或不应该在头文件/源文件中，甚至，因为某些语言并不真正使用头文件/源系统，什么是正确的注释方式.
到目前为止，我一直是这样做的:
main.c 或 main.cpp
int main()
{
// Comments to describe what happens in main
}
foo.h
// Comments for documentation and which gives information about the function itself
/**
* \fn void aFunction(void)
* \brief This function is a function
*/
void aFunction(void);
foo.c 或 foo.cpp
void aFunction(void)
{
// Comments to describe and explain what happens within this function
}
- main 中的注释不多，只是描述了基本调用了哪些函数以及为什么调用
- 在标题中，仅注释描述函数本身；参数、简介、返回等。
- 在源代码中，仅注释来描述函数中发生的事情；循环、条件等。
这就是我所知道的。 main、source 或 header 中是否需要更多注释？我是否也应该添加我通常只放在源头中的注释，像这样:
foo.c 或 foo.cpp
/**
* \fn void aFunction(void)
* \brief This function is a function
*/
void aFunction(void)
{
// Comments to describe and explain what happens within this function
}
我知道这听起来可能很主观，但显而易见的事实是，有些开发者比其他开发者更擅长发表评论，因此发表评论的方式有好有坏。