我正在寻找一种“最佳实践”来记录我的 C 代码。就像在任何项目中一样，我有一些头文件“.h”和相应的源文件“.c”
在头文件中你放了什么样的注释？在源文件中？ 问题出现了，因为我的头文件注释得很好，所以 c 文件看起来很乱。
您在保持代码注释良好方面的最佳做法是什么？
【问题讨论】：
标签： c documentation comments
标头用于代码的用户。所以在那里我记录了接口：如何使用它、前置条件和后置条件等等。
.c 文件用于维护者。在那里，我记录了实现：事情在内部是如何工作的，以及它们为什么会这样工作。
【讨论】：
The header is meant for users of the code and also for maintainers
我建议采用Doxygen 之类的工具强加的约定。然后，您不仅可以编写代码 cmets，还可以生成 HTML/PDF/Latex 等文档，它为您提供了良好的约定。
同意 Thomas 关于 cpp 文件的意见
【讨论】：
如果这是一个个人项目，我建议您可以采用大量的coding standards（几乎所有内容都包含有关如何布置 cmets 的部分）。
如果没有，我想你的公司/团队/项目已经有了一些东西，所以使用它。
【讨论】：
对于源文件，我建议你为文件头和函数头创建一个注释模板。
如果是文件头注释，您应该有文件的简要说明、函数名称、作者、创建日期和历史记录以记录修改。
在函数头的情况下，可以说明函数的逻辑和用途以及各种参数。请确保通过 cmets 详细记录任何复杂的逻辑或与常见行为的偏差。
【讨论】：