kirancodes.me
To Proof Maintenance & Beyond!
ICSE 2018

When not to comment: questions and tradeoffs with API documentation for C++ projects

Andrew Head, Caitlin Sadowski, Emerson R. Murphy-Hill, Andrea Knight

PDFDOI 10.1145/3180155.3180176dblp

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.

BibTeX
@inproceedings{Head-al:ICSE18,
  author    = {Andrew Head and
               Caitlin Sadowski and
               Emerson R. Murphy{-}Hill and
               Andrea Knight},
  title     = {When not to comment: questions and tradeoffs with {API} documentation for C++ projects},
  booktitle = {ICSE},
  pages     = {643--653},
  publisher = {{ACM}},
  year      = {2018},
}

Related papers