代码之家 › 专栏 › 技术社区 › Laserallan

C/C++头文件文档[已关闭]

javadoc documentation c c++

Laserallan · 技术社区 · 17 年前

您认为在C++中创建公共头文件的最佳实践是什么?

头文件应该不包含、简短或大量文档吗?我见过各种各样的东西,从几乎没有文档(依赖于一些外部文档)到大量的不变量、有效参数、返回值等规范。我不确定我到底更喜欢什么,大型文档是很好的,因为你总是可以从编辑器访问它,另一方面,一个包含非常简短文档的头文件通常可以在一两页文本上显示一个完整的界面,从而更好地概述一个类可以做什么。
假设我使用的是简短或大量的文档。我想要类似于javadoc的东西,在那里我记录返回值、参数等。c++中最好的约定是什么?据我所知,doxygen对javadoc风格的文档做得很好,但在使用javadoc风格文档之前,我应该知道还有其他的约定和工具吗?

5 回复 | 直到 17 年前

mouviciel 17 年前

通常我会把接口的文档(参数、返回值、, 什么函数do)在接口文件(.h)中,以及实现的文档( 怎样函数确实如此)在实现文件(.c、.cpp、.m)中。

在类声明之前,我写了一个类的概述,这样读者就可以立即获得基本信息。

我使用的工具是Doxygen。

Joao da Silva 17 年前

我肯定会在头文件中有一些文档。将信息放在代码旁边,而不是放在单独的文档中,这大大改善了调试。根据经验,我会在代码旁边记录API(返回值、参数、状态更改等),并在单独的文档中记录高级体系结构概述(以更广泛地了解所有内容的组合方式;很难将其与代码放在一起,因为它通常同时引用多个类)。
根据我的经验,Doxygen很好。

falstro 17 年前

我相信Doxygen是生成文档最常见的平台,据我所知,它或多或少能够涵盖JavaDoc符号(当然不仅限于此)。我在C中使用了doxygen,结果还可以,但我确实认为它更适合C++。你可能也想研究robodoc,尽管我认为奥卡姆剃刀会告诉你宁愿选择Doxygen。

关于文档的数量,我自己从来都不是文档迷,但无论我喜欢与否,拥有更多的文档总是比没有文档好。我会把API-文档放在头文件中,把实现文档放在实现中(这是理所当然的,不是吗?)。:)这样,IDE就有机会在自动补全过程中拾取并显示它(例如,Eclipse对JavaDocs也这样做,也许对doxygen也是如此?),这不应该被低估。JavaDoc有一个额外的怪癖,它使用第一句话(即直到第一个句号)作为简要描述,虽然不知道Doxygen是否这样做,但如果是这样,在编写文档时应该考虑到这一点。

有很多文档可能会过时,但是,将文档放在代码附近会让人们有机会保持最新,所以你一定要把它保存在源代码/头文件中。但不应该忘记的是文件的制作。是的,有些人会直接使用文档(通过IDE或其他方式,或者只是读取头文件),但有些人更喜欢其他方式,因此您可能应该考虑将(定期更新的)API文档放在网上,所有这些都很好,都可以浏览,如果您的目标是基于*nix的开发人员,还可以制作科幻小说。

那是我的两分钱。

Pete Kirkham 17 年前

在代码中加入足够的内容,使其能够独立运行。我参与过的几乎每个项目,文件都是单独的,要么已经过时,要么没有完成,部分原因是如果它是一个单独的文件,它就变成了一项单独的任务,部分原因在于管理层不允许将其作为预算中的任务。根据我的经验,将内联记录作为流程的一部分效果要好得多。

以大多数编辑认为是块的形式编写文档;对于C++来说,这似乎是/*而不是//。这样你就可以折叠它,只看到声明。

kliketa 17 年前

也许你会感兴趣 gtk-doc 。它可能“设置和使用起来有点尴尬”,但您可以从源代码中获得一个很好的API文档,如下所示:

String Utility Functions