Cla*_*diu 40 c documentation comments header-files
我有一个包含多个文件的C程序,所以我有,例如,stuff.c它实现了一些函数,并stuff.h使用函数原型.
我该如何记录评论中的功能？
我应该在头文件中包含所有文档,文件中的所有文档.c,还是复制两者的文档？我喜欢后一种方法,但后来我遇到问题,我将更新其中一个文档而不是另一个(通常是我进行第一次修改的文件,即如果我先修改头文件,那么它的注释)将反映这一点,但如果我更新实施,只会更改那些评论).
这个问题及其答案也适用于C++代码 - 另请参阅我应该在哪里放置文档注释？
我喜欢关注Google C++ 样式指南.
哪个说:
功能声明
功能定义
每个函数定义都应该有一个注释来描述函数的作用以及它如何完成它的工作.例如,在定义注释中,您可能会描述您使用的任何编码技巧,概述您所经历的步骤,或解释为什么选择以您的方式实现该功能而不是使用可行的替代方法.例如,您可能会提到为什么它必须为函数的前半部分获取锁定,但为什么下半部分不需要它.
请注意,您不应只重复使用函数声明,.h文件或任何位置给出的注释.可以简要概括一下这个函数的作用,但评论的重点应放在它是如何做到的.
我在这上面来回走动,最后我决定使用头文件中的文档.对于C/C++中的绝大多数API,您可以访问原始头文件,因此可以访问[1]中的所有注释.在这里发表评论可以最大限度地提高开发人员看到它们
我避免在头文件和源文件之间重复注释(这只是一种浪费).使用Vim时真的很烦人,但是大多数IDE都会获取头文件注释并将它们放入intellisense或参数帮助等内容中.
[1]此规则的例外情况包括从某些COM库生成的头文件.
它通常取决于设置的编码标准.许多人更喜欢将文档放在.h文件中,并将实现保留在.c文件中.许多带有代码完成功能的IDE也会更容易上传,而不是.c文件中的文档.
但我认为将文档放在.h文件中的主要问题是编写将与另一个程序共享的库或程序集.想象一下,您正在编写包含将要分发的组件的.dll(或.so).其他程序员将包括你的.h,但他们通常不会(也不需要)它背后的实现文件.在这种情况下,.h文件中的文档非常有用.
当你在同一个程序中编写一个类时,也可以这样说.如果您正在与其他程序员合作,那么大多数程序员通常只是查看头文件以了解如何与代码进行交互,而不是如何实现代码.如何实现它不是将使用该组件的人员或代码的关注.因此,标题中的文档将再次帮助那个人或那些人弄清楚如何使用该代码.
| 归档时间： |
|
| 查看次数： |
9844 次 |
| 最近记录： |