Suboptimal Comments in Java Projects: From Independent Comment Changes to Commenting Practices
Suboptimal Comments in Java Projects: From Independent Comment Changes to Commenting Practices
复制标题
DOI：
10.1145/3546949
复制
发表时间：
2022-07
影响因子：
4.4
通讯作者：
Chao Wang;Hao He;Uma Pal;D. Marinov;Minghui Zhou
中科院分区：
文献类型：
--
作者：
Chao Wang;Hao He;Uma Pal;D. Marinov;Minghui Zhou
高质量的源代码注释对于软件开发和维护是有价值的，然而，代码通常包含低质量的注释或完全没有注释。我们将这种源代码注释命名为次优注释。这种不理想的注释在代码理解和维护方面带来了挑战。尽管对低质量的源代码注释进行了大量的研究，但缺乏关于产生次优注释的注释实践和导致次优注释的原因的经验知识。我们通过调查（1）独立注释更改（ICC）-独立于代码更改提交的注释更改-这可能解决次优注释，（2）注释指南，以及（3）注释检查工具和注释生成工具，这些工具通常用于帮助注释实践-特别是防止次优注释。我们从4，392个开源GitHub Java存储库中收集了24 M+评论更改，并发现ICC广泛存在。ICC比率（ICC在所有注释更改中的比例）约为15.5%，98.7%的存储库具有ICC。我们对3，533个随机抽样的ICC进行了主题分析，提供了一个三维分类法，包括改变了什么（4个评论类别和13个子类别），如何改变（6个评论活动类别），以及哪些因素与变化相关（3个因素）。我们调查了600个仓库，以了解评论准则的流行程度、内容、影响和违反情况。我们发现，在600个抽样的存储库中，只有15.5%有任何评论指南。我们在注释指南中为元素提供了第一个分类法：在哪里注释和注释什么特别重要。没有此类准则的存储库的ICC比率在统计上显著更高，表明缺乏评论准则的负面影响。然而，注释指南并没有得到严格遵守：85.5%的受检查的存储库存在违规行为。我们还系统地研究了开发人员如何使用两种工具，评论检查工具和评论生成工具，在4,392个仓库。我们发现，Javadoc工具的使用与ICC比率呈负相关，而Checkstyle的使用没有统计学意义的相关性;评论生成工具的使用导致更高的ICC比率。最后，我们揭示了当前评论实践中的问题和挑战，这有助于理解次优评论是如何引入的。我们提出了评论位置预测，评论生成和评论质量评估的潜在研究方向，建议开发人员如何制定评论准则和执行规则的工具，并建议如何增强当前的评论检查和评论生成工具。
High-quality source code comments are valuable for software development and maintenance, however, code often contains low-quality comments or lacks them altogether. We name such source code comments as suboptimal comments. Such suboptimal comments create challenges in code comprehension and maintenance. Despite substantial research on low-quality source code comments, empirical knowledge about commenting practices that produce suboptimal comments and reasons that lead to suboptimal comments are lacking. We help bridge this knowledge gap by investigating (1) independent comment changes (ICCs)—comment changes committed independently of code changes—which likely address suboptimal comments, (2) commenting guidelines, and (3) comment-checking tools and comment-generating tools, which are often employed to help commenting practice—especially to prevent suboptimal comments. We collect 24M+ comment changes from 4,392 open-source GitHub Java repositories and find that ICCs widely exist. The ICC ratio—proportion of ICCs among all comment changes—is ~15.5%, with 98.7% of the repositories having ICC. Our thematic analysis of 3,533 randomly sampled ICCs provides a three-dimensional taxonomy for what is changed (four comment categories and 13 subcategories), how it changed (six commenting activity categories), and what factors are associated with the change (three factors). We investigate 600 repositories to understand the prevalence, content, impact, and violations of commenting guidelines. We find that only 15.5% of the 600 sampled repositories have any commenting guidelines. We provide the first taxonomy for elements in commenting guidelines: where and what to comment are particularly important. The repositories without such guidelines have a statistically significantly higher ICC ratio, indicating the negative impact of the lack of commenting guidelines. However, commenting guidelines are not strictly followed: 85.5% of checked repositories have violations. We also systematically study how developers use two kinds of tools, comment-checking tools and comment-generating tools, in the 4,392 repositories. We find that the use of Javadoc tool is negatively correlated with the ICC ratio, while the use of Checkstyle has no statistically significant correlation; the use of comment-generating tools leads to a higher ICC ratio. To conclude, we reveal issues and challenges in current commenting practice, which help understand how suboptimal comments are introduced. We propose potential research directions on comment location prediction, comment generation, and comment quality assessment; suggest how developers can formulate commenting guidelines and enforce rules with tools; and recommend how to enhance current comment-checking and comment-generating tools.