Question

This is a very simple question which I am surprised I haven't found anywhere else on SO. I was wondering which comments should or shall not be in header/source files. Which would be redondant or required if declared on both header and source. So far I have been doing it like that :

main.c or 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 or foo.cpp

void aFunction(void)
{
    // Comments to describe and explain what happens within this function
}

Not much comments in main, just describing basically what functions are called and why
In header, only comments to describe the function itself; parameters, brief, return etc.
In source, only comments to describe what's happening within the function; loops, condition, etc.

That is what I know for sure. Are there more comments needed in either main, source or header ? Should I add the comments I usually only put in the header in the source too, like that :

foo.c or 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
}

I know this is kind of subjective, but also I think commenting is an Art, and Art nonetheless subjective, needs to be technical.

Answer 1

C文件应包含您在编写代码时在任何地方编写的常用注释。它做了什么以及为什么做。通常在每一行的末尾，除非需要更广泛的评论。

H文件可以包含一个简短的最小值，解释函数作为参数的内容以及它返回的内容。或者它可以包含有关如何使用该函数的完整文档。如果头文件中未提供完整文档，则必须单独编写。注意：几行Doxygen垃圾只是为了产生一些无用的文件＆＃34;文件不算作完整的文档。

H文件记录了函数的功能以及如何使用它，而没有提到实现细节。重要的是要认识到h文件应该是相应c文件（或库）的完整独立接口。调用者需要注意的所有类型和依赖项（包括）都应该出现在h文件中。

这包括任何前置条件和后置条件：在调用函数之前需要执行哪些操作？该功能使用了哪些资源？它是否留下任何需要在以后清理的句柄/文件/资源？它改变了一些全球状态吗？等等。

相应的c文件不一定对用户可用，用户也不需要读取c文件以了解应该如何使用它们的功能。一切都应该从单独的h文件中显而易见。

Answer 2

就个人而言，我的经验法则是尽可能避免评论。

尽可能做到这一点;

通过适当选择类型名称，常量，枚举值，函数名称，变量名称等，使标题中的声明自我记录;
使函数定义尽可能小而简单，使它们尽可能清楚地表达它们的作用。通过适当选择变量名，本地类型等，使函数尽可能自我记录。将大函数分解为一组较小的函数，并使所有函数尽可能自我记录。
选择文件名（用于标题和编译单元），因此功能和声明的分组是显而易见的。

然后仅在需要时通过查看代码本身来解释不明显的内容时使用注释。例如，最好解释为什么代码执行某些操作，并允许代码本身描述HOW。如果一个函数具有特定的前提条件（在调用时假定为真的事物）或后置条件（如果满足前提条件，则函数在返回时保证为真），那么这些可以在注释中描述。

我不会将评论用于跟踪版本历史记录（这就是版本控制系统的用途）。

有时候，以简单明了的方式编写代码是不可能的。在这些情况下，需要提出意见。但是注释的问题（例如忘记更新它们，因此它们不再与代码相对应）是如此重要，最好是努力工作，这样代码 - 没有注释 - 尽可能地描述自己。

这也意味着要努力避免含糊不清的代码。不要写出带有25种副作用的陈述。缩进代码使其与实际结构一致（代码格式化程序可以帮助解决此问题）。尽可能避免使用宏（因为它们可以做与范围不一致的事情）。

Write comments in source or header file

2 个答案: