在哪里记录C或C ++中的函数？ [英] Where to document functions in C or C++?

问题描述

我有一个包含多个文件的C程序，所以我有例如实现某些功能的 stuff.c 和 stuff。 h 带有函数原型。

I have a C program with multiple files, so I have, for example, stuff.c which implements a few functions, and stuff.h with the function prototypes.

我应该如何在注释中记录函数？

How should I go about documenting the functions in comments?

我应该在头文件中包含所有文档，还是在 .c 文件中包含所有文档，或者同时复制这两个文档？我喜欢后一种方法，但是随后遇到的问题是，我将在其中一个而不是另一个上更新文档（通常是我进行第一次修改的文档，即如果先修改头文件，然后修改其注释）会反映出来，但是如果我更新实现，则只会更改那些注释。）

Should I have all the docs in the header file, all the docs in the .c file, or duplicate the docs for both? I like the latter approach, but then I run into problems where I'll update the docs on one of them and not the other (usually the one where I make the first modification, i.e. if I modify the header file first, then its comments will reflect that, but if I update the implementation, only those comments will change).

此问题及其答案也适用于C ++代码-另请参见我应该在哪里放置文档注释？

This question and its answers also apply to C++ code — see also Where should I put documentation comments?

推荐答案

• 将使用该功能的人需要知道的信息放在标题中。

  • Put the information that people using the functions need to know in the header.

    将信息保留给维护者函数需要在源代码中知道。

    Put the information that maintainers of the functions need to know in the source code.

    这篇关于在哪里记录C或C ++中的函数？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！