When Not to Comment: Questions and Tradeoffs with API Documentation for C++ Projects
When Not to Comment: Questions and Tradeoffs with API Documentation for C++ Projects
复制标题
DOI：
10.1145/3180155.3180176
复制
发表时间：
2018-05
期刊：
影响因子：
--
通讯作者：
Andrew Head;Caitlin Sadowski;E. Murphy-Hill;Andrea Knight
中科院分区：
文献类型：
--
作者：
Andrew Head;Caitlin Sadowski;E. Murphy-Hill;Andrea Knight
如果没有关于如何使用 API 的可用且准确的文档，开发人员可能会发现自己无法重用相关代码。在 C++ 中，开发人员可以在头文件中找到文档。当信息缺失时，他们可能会查看相应的实现代码。为了了解 C++ API 文档中缺失的内容以及影响是否修复的因素，我们进行了一项混合方法研究，其中包括对数百名开发人员在访问实现代码时进行的两次经验抽样调查、对其中 18 名开发人员的访谈以及对 8 位 API 维护人员的访谈。在许多情况下，更新文档可能只能为开发人员提供有限的价值，同时需要维护人员不愿意投入的精力。我们确定了维护人员和工具开发人员在改进 API 级文档时应考虑的一系列问题。
Without usable and accurate documentation of how to use an API, developers can find themselves deterred from reusing relevant code. In C++, one place developers can find documentation is in a header file. When information is missing, they may look at the corresponding implementation code. To understand what's missing from C++ API documentation and the factors influencing whether it will be fixed, we conducted a mixed-methods study involving two experience sampling surveys with hundreds of developers at the moment they visited implementation code, interviews with 18 of those developers, and interviews with 8 API maintainers. In many cases, updating documentation may provide only limited value for developers, while requiring effort maintainers don't want to invest. We identify a set of questions maintainers and tool developers should consider when improving API-level documentation.