如何正确评论

Question

这是一个非常简单的问题，令我惊讶的是我在 SO 上没有找到其他任何地方。我想知道 哪些注释应该或不应该在 header/source 文件中 甚至，因为有些语言并不真正使用 header/source 系统，评论的正确方式是什么.

到目前为止，我一直都是这样做的：

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 中的注释不多，只是描述基本调用了哪些函数以及为什么
在header中，仅注释描述函数本身；参数、简介、return 等
在源代码中，只有注释来描述函数中发生的事情；循环、条件等

这就是我所知道的。 main、source 或 header 中是否需要更多评论？我是否也应该添加我通常只放在源代码 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
}

我知道这听起来可能很主观，但显而易见的事实是，有些开发者比其他开发者更擅长发表评论，因此发表评论的方式有好有坏。

Answer 1

C 文件应该包含您编写代码时随处编写的常用注释。它是做什么的，为什么。通常在每一行的末尾，除非需要更广泛的注释。

H 文件可以包含一个简短的最小值，解释一个函数将什么作为参数以及它returns。或者，它可以包含有关应如何使用该功能的完整文档。如果头文件中没有提供完整的文档，您将不得不单独编写。注意：几行 Doxygen 废话只是为了生成某种无用的 "documentation" 文件，不算作完整的文档。

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

这包括任何前置条件和 post 条件：调用函数之前需要执行什么？该功能使用了哪些资源？它是否留下了任何需要稍后清理的 handles/files/resources ？它是否改变了一些全局状态？等等等等

不一定向用户提供相应的 c 文件，用户也不需要阅读 c 文件以了解应如何使用其中的功能。仅从 h 文件中，一切都应该变得显而易见。

Answer 2

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

尽可能做到这一点；

Make declarations in headers self-documenting by appropriate choice of type names, constants, enumerated values, function names, variable names, etc;
使函数定义尽可能小和简单，尽可能清楚地说明它们是如何做的。 Make the functions as self-documenting as possible by appropriate choice of variable names, local types, etc etc. Break big functions into a set of smaller functions, and make ALL of the functions as self-documenting as possible.
选择文件名（针对 headers 和编译单元）以便函数和声明的分组很明显。

然后仅在需要通过查看代码本身来解释不明显的内容时才使用注释。例如，最好解释为什么代码做某事，并允许代码本身描述 HOW。如果一个函数有特定的前提条件（当它被调用时假定为真）或 post 条件（当它 returns 如果满足前提条件时函数保证为真）那么这些可以被描述在评论中。

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

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

这也意味着努力避免神秘代码。不要写有 25 个副作用的语句。缩进代码以使其与实际结构一致（代码格式化程序可以帮助实现这一点）。尽可能避免宏（因为它们可以做与范围不一致的事情）。

如何正确评论

How to properly comment

c++

c

comments

header-files