一句话:通过混合方法研究 C++ API 文档缺失与修复动因,指出更新文档未必有价值且维护者常不愿投入。
论文关注 C++ API 文档缺失问题:当头文件中的文档不可用或不准确时,开发者会被迫阅读实现代码。为理解 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.