在哪里记录 C 或 C++ 中的函数？ [关闭]

Posted 2023-02-21

【中文标题】在哪里记录 C 或 C++ 中的函数？ [关闭]

【英文标题】：Where to document functions in C or C++? [closed]

【发布时间】：2011-04-03 20:11:13

【问题描述】：

我有一个包含多个文件的 C 程序，所以我有，例如，stuff.c 实现了一些函数，stuff.h 具有函数原型。

我应该如何记录 cmets 中的函数？

我应该在头文件中保存所有文档，在 .c 文件中保存所有文档，还是为两者复制文档？我喜欢后一种方法，但后来我遇到了问题，我将更新其中一个文档而不是另一个（通常是我进行第一次修改的那个，即如果我先修改头文件，然后修改它的 cmets会反映这一点，但如果我更新实现，只有那些 cmets 会改变）。

这个问题及其答案也适用于 C++ 代码 — 另请参阅 Where should I put documentation comments?

【参考方案1】：

这通常取决于设置的编码标准。许多人喜欢将文档放在 .h 文件中，而将实现留在 .c 文件中。许多带有代码完成功能的 IDE 也更容易理解这一点，而不是 .c 文件中的文档。

但我认为将文档放在 .h 文件中的重点在于编写将与另一个程序共享的库或程序集。想象一下，您正在编写一个 .dll（或 .so），其中包含您将要分发的组件。其他程序员将包含您的 .h，但他们通常不会（也不需要）其背后的实现文件。在这种情况下，.h 文件中的文档非常宝贵。

当您编写一个用于同一程序的类时也是如此。如果您正在与其他程序员一起工作，通常这些程序员只是查看头文件以了解如何与您的代码进行交互，而不是查看代码是如何实现的。它是如何实现的不是将使用该组件的人员或代码所关心的。因此，标题中的文档将再次帮助该人或那些人弄清楚如何使用该代码。

【参考方案2】：

您应该使用doxygen 之类的工具，因此文档是由源代码中特制的 cmets 生成的。

【参考方案3】：

将使用函数的人需要知道的信息放在标题中。

把函数维护者需要知道的信息放在源代码中。

【参考方案4】：

我在这方面反复讨论，最终确定了头文件中的文档。对于 C/C++ 中的绝大多数 API，您可以访问原始头文件，因此可以访问 [1] 中的所有 cmets。将 cmets 放在这里可以最大限度地提高开发人员看到它们的机会。

我避免了头文件和源文件之间的 cmets 重复（感觉就像是浪费）。使用 Vim 时确实很烦人，但大多数 IDE 会选择头文件 cmets 并将它们放入诸如智能感知或参数帮助之类的东西中。

[1] 此规则的例外情况包括从某些 COM 库生成的头文件。

【参考方案5】：

考虑到人们可以使用这些函数，同时只拥有头文件和实现的编译版本。确保在标题中记录了使用函数所需的任何内容。实现细节可以记录在源代码中。

【参考方案6】：

绝对将文档保存在一个地方，以避免维护噩梦。就个人而言，您可能非常挑剔以保持两个副本同步，但下一个人不会。

使用doxygen 之类的东西来创建文档的“漂亮”版本。

【参考方案7】：

我喜欢关注 Google C++ Style Guide.

上面写着：

函数声明

每个函数声明都应该 前面有 cmets 它描述了什么功能 做以及如何使用它。这些 cmets 应该是描述性的 （“打开文件”）而不是 命令式（“打开文件”）；这 注释描述了功能，它 不告诉函数要做什么 做。一般来说，这些 cmets 不 描述函数如何执行 它的任务。相反，这应该是 留给函数中的 cmets 定义。

函数定义

每个函数定义都应该有 描述什么的评论 功能和任何棘手的事情 关于它是如何工作的。为了 例如，在定义注释中 您可能会描述任何编码技巧 你使用，给出一个概述 您经历的步骤，或解释原因 您选择实现该功能 以你做的方式而不是使用 一个可行的替代方案。例如， 你可能会提到为什么它必须获得 上半场的锁 功能，但为什么不需要它 下半场。

请注意，您不应该只是重复 用函数给出的 cmets 声明，在 .h 文件中或 无论在哪里。概括一下就好了 简要说明该功能的作用，但是 cmets的重点应该是 关于它是如何做到的。

【参考方案8】：

标头与实现文件中的 cmets 应反映两者使用方式的差异。

如果您要创建明显属于标题的接口文档（例如，使用 Doxygen 提取，与 JavaDocs 的一般顺序相同）。即使您不打算提取 cmets 以生成单独的文档，也适用相同的一般思想 - 解释接口/如何使用代码的 cmets，主要或仅属于标题。

实施中的评论通常应与实施相关。与常见的做法相反，大多数人应该解释为什么做出特定决定，而不是试图解释事情是如何运作的。当您做出有意义的决定时尤其如此，但它们可能并不明显（例如，请注意您确实没有使用快速排序，因为您需要稳定的排序）。

【参考方案9】：

仔细想想真的很简单。

API 文档绝对必须放在头文件中。它是定义外部接口的头文件，所以这就是 API 文档所在。

通常，API 用户应该隐藏实现细节。这包括实施文档（除非它可能影响使用，例如时间复杂度等）。因此，实现文档应该放在实现文件中。

永远不要在多个地方重复文档。它将无法维护，并且几乎一旦有人必须更改它就会不同步。

【参考方案10】：

我编写了一个简单的脚本，将一个没有函数声明的模板头文件和一个带有注释函数的源代码文件作为输入。该脚本从源代码文件中提取函数定义之前的注释，并将其和相关的函数声明写入输出头文件。这确保了 1) 只有一个地方需要编写函数注释； 2) 头文件和源代码文件中的文档始终保持同步。函数实现的注释放在函数体中，不会被提取出来。