C代码注释，头文件和源文件

Question

16

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

在头文件中，您要放置什么类型的注释？在源文件中呢？提出这个问题是因为由于我对头文件进行了良好的注释，所以C文件看起来很混乱。

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

- pygabriel

确保好好注释头文件并不意味着C文件就可以一团糟... - David Gelhar

这里可以找到一个类似的问题：https://dev59.com/DXRB5IYBdhLWcg3w3K4J - mouviciel

4个回答

8

我建议采用像Doxygen这样的工具所强制实施的约定。这样，您不仅可以生成代码注释，还可以生成HTML/PDF/Latex等文档，并且它为您提供了良好的约定。

我同意Thomas关于cpp文件的看法。

- Hannes de Jager

1

如果这是一个个人项目，我建议你可以采用很多编码标准（几乎所有的都包括如何布置注释的部分）。

如果不是，我想你的公司/团队/项目已经有了一些规定，请使用它们。

- Jon Cage

1

关于源文件，我建议为文件头和函数头创建注释模板。

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

对于函数头注释，您可以解释函数的逻辑和目的以及各种参数。请确保任何复杂的逻辑或与常规行为偏差的内容都通过注释进行了充分记录。

- Jay

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Thomas · Accepted Answer

头部注释是给代码的使用者看的。所以我在那里记录了接口：如何使用它，前置条件和后置条件等。

.c文件是给维护者看的。在那里，我记录了实现：内部运作方式及其原因。