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.

翻译：函数头注释或许是代码文档中使用最广泛的形式。我们开展了一项涉及367名开发者的大规模调查，以梳理他们对这类文档的预期，并记录实际实践情况。矛盾的是，我们发现开发者虽然认同头注释的价值，并认为值得投入时间去编写，但在自己编写的代码中却往往不会撰写这类文档。开发者不写头注释的原因各不相同，从认为代码本身应具备自文档性，到担心文档无法保持更新。这种状况可能导致一种结果：开发者可能通过使用模板生成毫无价值、不提供任何实际信息的注释来规避编写文档的要求。我们根据注释与函数签名的相似性，定义了一个衡量无信息文档的简单指标。将该指标应用于GitHub上Python项目中的21,140个文件后发现，大多数函数没有文档，但当编写了头注释时，它们通常确实包含了超出函数签名的额外信息。