评论C代码，标题和源文件

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

在头文件中你放了什么样的评论？ 在源文件中？ 问题出现了，因为我评论了我的头文件，c文件看起来像一团糟。

保持代码评论良好的最佳做法是什么？

Answer 1

标题适用于代码的用户 。 所以我在那里记录了界面 ：如何使用它，前置条件和后置条件等等。

.c文件适用于维护者 。 在那里，我记录了实现 ：内部如何工作，以及它们为何如此工作。

Answer 2

我建议采用像Doxygen这样的工具强加的约定。 然后，您还可以生成HTML / PDF / Latex等文档，而不仅仅是代码注释，它为您提供了良好的约定。

同意Thomas关于cpp文件

Answer 3

对于源文件，我建议您为File Header和Function Header创建一个注释模板。

在文件头注释的情况下，您应该具有文件，函数名称，作者，创建日期和记录修改历史的简要描述。

通过函数头，可以解释函数的逻辑和用途以及各种参数。 请确保通过注释充分记录任何复杂的逻辑或偏离常见行为。

Answer 4

如果这是一个个人项目，我建议您可以采用大量的编码标准 （几乎所有都包含有关如何布置评论的部分）。

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