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

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.

• Software Engineering