不过，我避免了头文件和源文件之间的重复注释（感觉就像浪费）。使用 Vim 时这确实很烦人，但大多数 IDE 都会获取头文件注释并将它们放入智能感知或参数帮助等内容中。
[1] 此规则的例外情况包括从某些 COM 库生成的头文件。
I've gone back and forth on this and eventually I settled on documentation in header files. For the vast majority of APIs in C/C++ you have access to the original header file and hence all of the comments that lie within [1]. Putting comments here maximizes the chance developers will see them.
I avoid duplication of comments between header and source files though (it just feels like a waste). It's really annoying when using Vim but most IDEs will pick up the header file comments and put them into things like intellisense or parameter help.
[1] Exceptions to this rule include generated header files from certain COM libraries.
It will often depend on what is set as the coding standard. Many people prefer to put the documentation in the .h file and leave the implementation in the .c file. Many IDE's with code completion will also pick up more easily on this rather than the documentation in the .c file.
But I think the major point in putting the documentation in the .h file deals with writing a library or assembly that will be shared with another program. Imagine that you're writing a .dll (or .so) that contains a component that you will be distributing. Other programmers will include your .h, but they often won't have (nor need) the implementation file behind it. In this case, documentation in the .h file is invaluable.
The same can be said when you're writing a class for use in the same program. If you're working with other programmers, most often those programmers are just looking at the header file for how to interact with your code rather than how the code is implemented. How it is implemented is not the concern of the person or code that will be using the component. So once again, documentation in the header will help that person or those people figure out how to use that code.
Consider that it's possible for people to use these functions while only having the headers and a compiled version of the implementation. Make sure that anything necessary for using your functions is documented in the header. Implementation details can be documented in the source.
The comments in the header vs. the implementation file should reflect the difference in how the two are used.
If you're going to create interface documentation (e.g., to be extracted with Doxygen, on the same general order as JavaDocs) that clearly belongs in the header. Even if you're not going to extract the comments to produce separate documentation, the same general idea applies -- comments that explain the interface/how to use the code, belong primarily or exclusively in the header.
Comments in the implementation should generally relate to the implementation. Contrary to frequent practice, rather than attempting to explain how things work, most should explain why particular decisions were made. This is especially true when you make decisions that make sense, but it might not be obvious that they do (e.g., noting that you did not use a Quicksort, because you need a stable sort).
一般来说，实施细节应该对 API 用户隐藏。这包括实现的文档（除非它可能影响使用，例如时间复杂度等）。因此，实施文档应该放在实施文件中。
切勿在多个地方重复文档。它将无法维护，并且几乎一旦有人必须更改它就会失去同步。
It's simple really when you think about it.
The API docs absolutely must go in the header file. It's the header file that defines the external interface, so that's where the API docs go.
As a rule, implementation details should be hidden from API users. This includes documentation of implementation (except where it might affect the use e.g. time complexity etc). Thus implementation documentation should go in the implementation file.
Never ever duplicate documentation in multiple places. It will be unmaintainable and will be out of sync almost as soon as somebody has to change it.
I wrote a simple script that takes as input a template header-file with no function declarations and a source-code file with commented functions. The script extracts the commentary before a function definition from the source code file and writes it and the associated function declaration into an output header-file. This ensures that 1) there's only one place where function commentary needs to be written; and 2) the documentation in the header-file and the source code file always remain in sync. Commentary on the implementation of a function is put into the body of the function and is not extracted.
Definitely keep the docs in one place, to avoid the maintenance nightmare. You, personally, might be fastidious enough to keep two copies in sync, but the next person wont.
Use something like doxygen to create a "pretty" version of the docs.
Every function declaration should have comments immediately preceding it that describe what the function does and how to use it. These comments should be descriptive ("Opens the file") rather than imperative ("Open the file"); the comment describes the function, it does not tell the function what to do. In general, these comments do not describe how the function performs its task. Instead, that should be left to comments in the function definition.
Function Definitions
Each function definition should have a comment describing what the function does and anything tricky about how it does its job. For example, in the definition comment you might describe any coding tricks you use, give an overview of the steps you go through, or explain why you chose to implement the function in the way you did rather than using a viable alternative. For instance, you might mention why it must acquire a lock for the first half of the function but why it is not needed for the second half.
Note you should not just repeat the comments given with the function declaration, in the .h file or wherever. It's okay to recapitulate briefly what the function does, but the focus of the comments should be on how it does it.
发布评论
评论（10）
我对此反复思考，最终我决定使用头文件中的文档。对于 C/C++ 中的绝大多数 API，您可以访问原始头文件，因此可以访问 [1] 中的所有注释。将评论放在这里可以最大限度地提高开发人员看到它们的机会。
不过，我避免了头文件和源文件之间的重复注释（感觉就像浪费）。使用 Vim 时这确实很烦人，但大多数 IDE 都会获取头文件注释并将它们放入智能感知或参数帮助等内容中。
[1] 此规则的例外情况包括从某些 COM 库生成的头文件。
I've gone back and forth on this and eventually I settled on documentation in header files. For the vast majority of APIs in C/C++ you have access to the original header file and hence all of the comments that lie within [1]. Putting comments here maximizes the chance developers will see them.
I avoid duplication of comments between header and source files though (it just feels like a waste). It's really annoying when using Vim but most IDEs will pick up the header file comments and put them into things like intellisense or parameter help.
[1] Exceptions to this rule include generated header files from certain COM libraries.
它通常取决于设置的编码标准。许多人喜欢将文档放在 .h 文件中，而将实现留在 .c 文件中。许多具有代码补全功能的 IDE 也会更容易地了解这一点，而不是 .c 文件中的文档。
但我认为将文档放入 .h 文件的主要目的是编写将与另一个程序共享的库或程序集。想象一下，您正在编写一个 .dll（或 .so），其中包含您将要分发的组件。其他程序员会包含您的 .h，但他们通常不会（也不需要）其背后的实现文件。在这种情况下，.h 文件中的文档非常宝贵。
当您编写在同一程序中使用的类时，也可以这样说。如果您与其他程序员一起工作，那么大多数情况下，这些程序员只是查看头文件以了解如何与您的代码交互，而不是如何实现代码。如何实现它并不是使用该组件的人员或代码所关心的。因此，标头中的文档将再次帮助该人或那些人弄清楚如何使用该代码。
It will often depend on what is set as the coding standard. Many people prefer to put the documentation in the .h file and leave the implementation in the .c file. Many IDE's with code completion will also pick up more easily on this rather than the documentation in the .c file.
But I think the major point in putting the documentation in the .h file deals with writing a library or assembly that will be shared with another program. Imagine that you're writing a .dll (or .so) that contains a component that you will be distributing. Other programmers will include your .h, but they often won't have (nor need) the implementation file behind it. In this case, documentation in the .h file is invaluable.
The same can be said when you're writing a class for use in the same program. If you're working with other programmers, most often those programmers are just looking at the header file for how to interact with your code rather than how the code is implemented. How it is implemented is not the concern of the person or code that will be using the component. So once again, documentation in the header will help that person or those people figure out how to use that code.
考虑到人们可以在仅拥有标头和实现的编译版本的情况下使用这些函数。确保使用函数所需的任何内容都记录在标题中。实现细节可以记录在源代码中。
Consider that it's possible for people to use these functions while only having the headers and a compiled version of the implementation. Make sure that anything necessary for using your functions is documented in the header. Implementation details can be documented in the source.
标头与实现文件中的注释应反映两者使用方式的差异。
如果您要创建显然属于标头的接口文档（例如，使用 Doxygen 提取，与 JavaDocs 的一般顺序相同）。即使您不打算提取注释来生成单独的文档，同样的一般思想也适用 - 解释接口/如何使用代码的注释主要或专门属于标头。
实施中的评论通常应该与实施相关。与常见的做法相反，大多数人应该解释为什么做出特定决定，而不是试图解释事物如何运作。当您做出有意义的决定时尤其如此，但它们可能并不明显（例如，注意到您没有使用快速排序，因为您需要稳定的排序）。
The comments in the header vs. the implementation file should reflect the difference in how the two are used.
If you're going to create interface documentation (e.g., to be extracted with Doxygen, on the same general order as JavaDocs) that clearly belongs in the header. Even if you're not going to extract the comments to produce separate documentation, the same general idea applies -- comments that explain the interface/how to use the code, belong primarily or exclusively in the header.
Comments in the implementation should generally relate to the implementation. Contrary to frequent practice, rather than attempting to explain how things work, most should explain why particular decisions were made. This is especially true when you make decisions that make sense, but it might not be obvious that they do (e.g., noting that you did not use a Quicksort, because you need a stable sort).
当你想一想时，这真的很简单。
API 文档绝对必须放在头文件中。它是定义外部接口的头文件，因此这就是 API 文档所在的位置。
一般来说，实施细节应该对 API 用户隐藏。这包括实现的文档（除非它可能影响使用，例如时间复杂度等）。因此，实施文档应该放在实施文件中。
切勿在多个地方重复文档。它将无法维护，并且几乎一旦有人必须更改它就会失去同步。
It's simple really when you think about it.
The API docs absolutely must go in the header file. It's the header file that defines the external interface, so that's where the API docs go.
As a rule, implementation details should be hidden from API users. This includes documentation of implementation (except where it might affect the use e.g. time complexity etc). Thus implementation documentation should go in the implementation file.
Never ever duplicate documentation in multiple places. It will be unmaintainable and will be out of sync almost as soon as somebody has to change it.
我编写了一个简单的脚本，它将没有函数声明的模板头文件和带有注释函数的源代码文件作为输入。该脚本从源代码文件中提取函数定义之前的注释，并将其和关联的函数声明写入输出头文件中。这确保了 1）只有一个地方需要编写函数注释； 2) 头文件中的文档和源代码文件始终保持同步。对函数实现的注释被放入函数体中并且不被提取。
I wrote a simple script that takes as input a template header-file with no function declarations and a source-code file with commented functions. The script extracts the commentary before a function definition from the source code file and writes it and the associated function declaration into an output header-file. This ensures that 1) there's only one place where function commentary needs to be written; and 2) the documentation in the header-file and the source code file always remain in sync. Commentary on the implementation of a function is put into the body of the function and is not extracted.
一定要将文档保存在一个地方，以避免维护噩梦。就你个人而言，可能会非常挑剔地保持两份副本同步，但下一个人不会。
使用诸如 doxygen 之类的东西来创建文档的“漂亮”版本。
Definitely keep the docs in one place, to avoid the maintenance nightmare. You, personally, might be fastidious enough to keep two copies in sync, but the next person wont.
Use something like doxygen to create a "pretty" version of the docs.
将使用功能的人需要了解的信息放在标题中。
将函数维护者需要了解的信息放在源代码中。
Put the information that people using the functions need to know in the header.
Put the information that maintainers of the functions need to know in the source code.
我喜欢遵循 Google C++ 样式指南。
其中说道：
I like to follow the Google C++ Style Guide.
Which says:
您应该使用像 doxygen 这样的工具，因此文档是由源代码中特制的注释生成的。
You should use a tool like doxygen, so the documentation is generated by specially crafted comments in your source code.