评论 C 代码、头文件和源文件 [关闭]

Posted 2023-02-21

【中文标题】评论 C 代码、头文件和源文件 [关闭]

【英文标题】：Commenting C code, header and source files [closed]

【发布时间】：2011-02-05 05:29:21

【问题描述】：

我正在寻找一种“最佳实践”来记录我的 C 代码。就像在任何项目中一样，我有一些头文件“.h”和相应的源文件“.c”

在头文件中你放了什么样的注释？在源文件中？ 问题出现了，因为我的头文件注释得很好，所以 c 文件看起来很乱。

您在保持代码注释良好方面的最佳做法是什么？

【问题讨论】：

当然已经很好地评论了你的标题是没有理由让 c 文件变得一团糟......

类似的问题可以在这里找到：***.com/questions/487114/…

【参考方案1】：

标头用于代码的用户。所以在那里我记录了接口：如何使用它、前置条件和后置条件等等。

.c 文件用于维护者。在那里，我记录了实现：事情在内部是如何工作的，以及它们为什么会这样工作。

【讨论】：

我会说The header is meant for users of the code and also for maintainers

【参考方案2】：

我建议采用Doxygen 之类的工具强加的约定。然后，您不仅可以编写代码 cmets，还可以生成 html/PDF/Latex 等文档，它为您提供了良好的约定。

同意 Thomas 关于 cpp 文件的意见

【参考方案3】：

如果这是一个个人项目，我建议您可以采用大量的coding standards（几乎所有内容都包含有关如何布置 cmets 的部分）。

如果没有，我想你的公司/团队/项目已经有了一些东西，所以使用它。

【参考方案4】：

对于源文件，我建议你为文件头和函数头创建一个注释模板。

如果是文件头注释，您应该有文件的简要说明、函数名称、作者、创建日期和历史记录以记录修改。

在函数头的情况下，可以说明函数的逻辑和用途以及各种参数。请确保通过 cmets 详细记录任何复杂的逻辑或与常见行为的偏差。