paperbot · PL 论文追踪

全部论文 待读 收藏

P2 When not to comment

何时不注释
ICSE Proceedings of the 40th International Conference on Software Engineering2018匹配度 1/10 · 该论文属于软件工程中 API 文档缺失与维护动因的实证/混合方法研究,关注开发者行为与文档修复意愿,不涉及静态分析、LLM/Agent、浮点程序分析或贝叶斯程序分析。引用 22 inbox
Andrew Head, Caitlin Sadowski, Emerson Murphy-Hill, Andrea Knight
crossref: 2026-09-12

AI 速览

一句话:通过混合方法研究 C++ API 文档缺失与修复动因,指出更新文档未必有价值且维护者常不愿投入。

论文关注 C++ API 文档缺失问题:当头文件中的文档不可用或不准确时,开发者会被迫阅读实现代码。为理解 API 文档中缺失什么以及哪些因素影响其被修复,作者开展混合方法研究,包括两次经验采样调查(在数百名开发者查看实现代码的时刻进行)、对其中 18 名开发者的访谈,以及对 8 名 API 维护者的访谈。研究发现,许多情况下更新文档对开发者的价值有限,同时却需要维护者不愿投入的精力。基于此,论文提出了一组维护者和工具开发者应思考的问题,以指导 API 级文档的改进。

问题
C++ API 文档常不完整或不可用,开发者在头文件信息缺失时只能阅读实现代码;研究希望理解文档缺失内容及影响其是否被修复的因素。
方法
采用混合方法:两次针对数百名开发者的经验采样调查(在其访问实现代码时触发)、对 18 名开发者的访谈,以及对 8 名 API 维护者的访谈。
评估
通过调查与访谈的定性/定量分析,识别文档更新对开发者的实际价值与维护者投入意愿之间的关系,并总结维护者和工具开发者应关注的问题。
原文摘要(Abstract)

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.

链接与引用

DOI 原文 · PDF(开放获取) ·

BibTeX
@inproceedings{paperbot4398,
  title = {When not to comment},
  author = {Andrew Head and Caitlin Sadowski and Emerson Murphy-Hill and Andrea Knight},
  booktitle = {ICSE},
  year = {2018},
  doi = {10.1145/3180155.3180176}
}