注释是否遵循注释规范?以 Java 和 Python 为例的研究
软件工程
2023-04-26 v2
摘要
评估代码注释质量是一个公认的难题。人们已制定若干编码风格指南,旨在鼓励编写信息丰富、可读且一致的注释。然而,迄今的研究尚不清楚这些指南具体涵盖注释的哪些方面(例如语法、内容、结构)。此外,开发人员在编写代码注释时遵循这些指南的程度也未知。我们分析了 Java 和 Python 中的各种风格指南,发现其中大多数更侧重于注释的内容方面而非语法或格式;但综合考虑开发人员在注释中嵌入的不同类型信息,以及他们在各类在线平台上对注释实践提出的关切,现有注释规范既未足够明确,也未能充分涵盖重要关切。我们还分析了不同项目中开发人员的注释实践,以考察他们对指南的遵循程度。我们的结果凸显了开发人员注释实践与风格指南之间的不匹配,并为注释质量检查工具的设计与改进提供了若干焦点。
引用
@article{arxiv.2108.10766,
title = {Do Comments follow Commenting Conventions? A Case Study in Java and Python},
author = {Pooja Rani and Suada Abukar and Nataliia Stulova and Alexandre Bergel and Oscar Nierstrasz},
journal= {arXiv preprint arXiv:2108.10766},
year = {2023}
}
备注
5 pages, 3 figures, conference