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

Question

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

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

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

Answer 1

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

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

Answer 2

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

同意Thomas关于cpp文件

Answer 3

如果这是一个个人项目，我建议你可以采用很多coding standards（几乎所有都包括如何布置评论的部分）。

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

Answer 4

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

如果是文件头注释，您应该对文件，函数名称，作者，创建日期和记录修改的历史进行简要描述。

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