Google Research

When Not to Comment: Questions and Tradeoffs with API Documentation for C++ Projects

International Conference on Software Engineering (ICSE) (2018) (to appear)

Abstract

Without usable and accurate documentation of how to use an API, programmers can find themselves deterred from reusing relevant code. In C++, one place developers can find documentation is in a header file, but when information is missing, they may look at the corresponding implementation (the “.cc” file). To understand what’s missing from C++ API documentation and whether it should be fixed, we conducted a mixed-methods study. This involved three experience sampling studies with hundreds of developers at the moment they visited implementation code, interviews with 18 of those developers, and interviews with 8 API maintainers. We found that in many cases, updating documentation may provide only limited value for developers, while requiring effort maintainers don’t want to invest. This helps frame future tools and processes designed to fill in missing low-level API documentation.

Research Areas

Learn more about how we do research

We maintain a portfolio of research projects, providing individuals and teams the freedom to emphasize specific types of work