在C文件中的function在哪里？
我有一个C程序与多个文件，所以我有，例如， stuff.c ，它实现了几个函数，并与函数原型stuff.h 。
我应该如何去logging评论中的function？
我是否应该将头文件中的所有文档， .c文件中的所有文档都复制到两个文档中？ 我喜欢后一种方法，但后来我遇到了问题，我将其中一个更新文档，而不是其他（通常是我第一次修改，即如果我首先修改头文件，然后其评论会反映，但如果我更新实施，只有这些意见将改变）。
-
把使用这些function的人需要知道的信息放在头里。
-
把源代码中需要知道的function维护者的信息。
你应该使用像doxygen这样的工具，所以文档是通过源代码中特制的注释生成的。
我喜欢遵循Google C ++ 风格指南。
其中说：
函数声明
- 每个函数声明都应该在其之前有注释，描述函数的function以及如何使用它。 这些注释应该是描述性的（“打开文件”）而不是命令性的（“打开文件”）; 注释描述了这个函数，它并不告诉函数该做什么。 一般来说，这些评论没有描述function如何执行其任务。 相反，这应该留给在函数定义中的注释。
function定义
-
每个函数定义都应该有一个注释来描述这个函数的作用，以及关于它如何工作的棘手问题。 例如，在定义注释中，您可能会描述所使用的任何编码技巧，概述您所经历的步骤，或解释为什么select以您所采用的方式实现该function，而不是使用可行的替代方法。 例如，你可能会提到为什么它必须为函数的前半部分获得一个锁，但是为什么在下半部分不需要。
请注意，您不应该重复使用函数声明给出的注释，在.h文件或任何地方。 简单地重述一下这个function的作用是可以的，但是评论的重点应该放在如何做。
我已经在这个来回，最终我在文件头文件中解决。 对于C / C ++中的绝大多数API，您可以访问原始头文件，因此可以访问[1]中的所有注释。 在这里发表评论会使开发人员看到他们的机会最大化。
我避免了头文件和源文件之间的注释重复（它只是觉得很浪费）。 使用Vim的时候真的很烦人，但是大多数IDE会拿起头文件的注释，并把它们放到像intellisense或者参数帮助的东西里。
[1]此规则的例外包括从某些COM库生成的头文件。
它通常取决于编码标准。 许多人喜欢将文档放在.h文件中，并将实现保留在.c文件中。 许多带有代码完成function的IDE也会在这个文件中比在.c文件中更容易获取。
但我认为将文档放在.h文件中的主要问题在于编写将与另一个程序共享的库或程序集。 想象一下，你正在编写一个.dll（或.so），它包含你将要发布的组件。 其他程序员将包括你的.h，但他们往往不会有（也不需要）在它后面的实现文件。 在这种情况下，.h文件中的文档是非常有用的。
当你正在写同一个程序中使用的类时，也可以这样说。 如果您正在与其他程序员一起工作，那么大多数程序员通常只是在头文件中查看如何与代码交互，而不是如何实现代码。 它是如何实现的不是使用该组件的人或代码的关注。 所以再次，头文件将帮助那些人或那些人找出如何使用该代码。
你可以简单地使用Doxygen ..此外，你可以看看这个答案 。
考虑到人们可以使用这些函数，而只有头文件和编译版本的实现。 确保使用您的function所需的任何内容都logging在标题中。 实施细节可以在源文件中logging。
绝对保持在一个地方的文档，以避免维护的噩梦。 你个人来说，可能会让两个副本保持同步，但下一个人却不会。
使用像Doxygen这样的东西来创build一个“漂亮”版本的文档。
当你想到这件事真的很简单。
API文档绝对必须放在头文件中。 它是定义外部接口的头文件，所以这就是API文档去的地方。
通常，API用户应该隐藏实现细节。 这包括实施文件（除了可能影响使用的时间，例如时间复杂度等）。 因此实现文档应该放在实现文件中。
永远不要在多个地方复制文档。 这将是不可维护的，几乎只要有人需要改变它就会不同步。
我写了一个简单的脚本，input一个没有函数声明的模板头文件和带注释函数的源代码文件。 脚本从源代码文件中提取函数定义之前的注释，并将其和相关的函数声明写入输出头文件。 这确保了1）只有一个function评论需要写的地方; 2）头文件和源代码文件中的文档始终保持同步。 函数实现的注释被放入函数的主体中，而不是被提取出来。
标题中的注释与实现文件应该反映两者如何使用的差异。
如果您打算创build接口文档（例如，用Doxygen提取，与JavaDocs相同的一般顺序），该文档清楚地属于头文件。 即使你不会提取注释来生成单独的文档，也应该使用相同的总体思路 – 解释界面/如何使用代码的注释主要属于或仅包含在头文件中。
执行中的意见通常应与实施有关。 与经常的做法相反，不是试图解释事情是如何工作的，大多数人应该解释为什么做出特定的决定。 当你做出有意义的决定时尤其如此，但是它们可能并不明显（例如，由于需要稳定的sorting，因此注意不使用Quicksort）。
