The Paradox of Function Header Comments
Arthur Oxenhorn, Almog Mor, Uri Stern, Dror G. Feitelson
TL;DR
The paper tackles the paradox of function header comments: developers acknowledge their value yet rarely produce them. It combines a global survey of 367 developers with a GitHub-based analysis of 21,140 Python files, introducing a simple metric to quantify meaningless documentation relative to function signatures. Key findings show a broad perceived usefulness of header comments and reliance on them for initial understanding, but substantial gaps in actual usage and guidelines, with examples frequently missing. Practically, the study suggests targeted guidelines that require header documentation for public/complex functions and emphasize including usage examples to improve comprehension and maintainability.
Abstract
Perhaps the most widely used form of code documentation is function header comments. We performed a large-scale survey of 367 developers to catalog their expectations from such documentation and to chronicle actual practice. Paradoxically, we found that developers appreciate the value of header comments and estimate that they are worth the investment in time, but nevertheless they tend not to write such documentation in their own code. Reasons for not writing header comments vary from the belief that code should be self-documenting to concern that documentation will not be kept up-to-date. A possible outcome of this situation is that developers may evade requirements to write documentation by using templates to generate worthless comments that do not provide any real information. We define a simple metric for information-less documentation based on its similarity to the function signature. Applying this to 21,140 files in GitHub Python projects shows that most functions are undocumented, but when header comments are written they typically do contain additional information beyond the function signature.