函数头注释的悖论

Arthur Oxenhorn; Almog Mor; Uri Stern; Dror G. Feitelson

函数头注释的悖论

软件工程 2024-01-17 v1

作者: Arthur Oxenhorn , Almog Mor , Uri Stern , Dror G. Feitelson

摘要

函数头注释可能是使用最广泛的代码文档形式。我们对367名开发者进行了大规模调查，以梳理他们对此类文档的期望并记录实际做法。矛盾的是，我们发现开发者认可头注释的价值，并估计其值得投入时间，但他们却往往不在自己的代码中编写此类文档。不编写头注释的原因多种多样，从认为代码应当自文档化，到担心文档无法保持更新。这种情况可能导致开发者通过使用模板生成毫无价值、不提供任何真实信息的注释来规避编写文档的要求。我们基于注释与函数签名的相似度，定义了一种衡量无信息文档的简单指标。将其应用于GitHub Python项目中的21,140个文件后发现，大多数函数都未编写文档，但当编写头注释时，它们通常确实包含了函数签名之外的额外信息。

关键词

函数头注释代码文档开发者调查无信息文档自文档化代码文档度量指标 GitHub Python项目

引用

@article{arxiv.2401.07704,
  title  = {The Paradox of Function Header Comments},
  author = {Arthur Oxenhorn and Almog Mor and Uri Stern and Dror G. Feitelson},
  journal= {arXiv preprint arXiv:2401.07704},
  year   = {2024}
}

备注

11 pages, 2 figures plus 23 inlined graphs

函数头注释的悖论

摘要

关键词

引用

备注

相关论文