Practitioners’ Expectations

Practitioners’ Expectations on Automated Code Comment Generation

@inproceedings{hu2022practitioners,
  title={Practitioners' expectations on automated code comment generation},
  author={Hu, Xing and Xia, Xin and Lo, David and Wan, Zhiyuan and Chen, Qiuyuan and Zimmermann, Thomas},
  booktitle={Proceedings of the 44th International Conference on Software Engineering},
  pages={1693--1705},
  year={2022}
}

0 Abstract

However, it is unclear whether these techniques can alleviate comment issues
and whether practitioners appreciate this line of research.
问题：然而，这些技术是否缓解了注释问题，以及从业者是否欣赏这一研究方向尚不清楚。

1 Introduction

尽管有大量关于代码注释生成的研究，但不幸的是，很少有研究调查了从业者对注释生成研究的期望。目前尚不清楚从业者是否欣赏这一研究方向。即使他们欣赏，也不清楚他们是否会采用代码注释生成工具，什么因素影响他们的采用决策，以及他们的最低采用门槛。从业者的观点对于帮助软件工程研究人员制定满足开发人员需求的解决方案至关重要。此外，一些从业者期望与研究之间的差距尚未得到调查。
为了获得从业者在代码注释生成上的期望
- 我们首先对16位各个公司的专家进行了半结构化的采访。通过采访，我们量化了采访者在编程实践中的注释时间和问题，以及他们对自动注释生成的期望。
- 随后我们从720个开发者的问卷调研中验证了我们的想法，这些开发者来自26个国家6个大洲。
- 在调查之后，我们进行了对最新论文的文献回顾。然后，我们将论文中提出的技术与从业者采用的标准进行了比较。
我们将探究以下4个研究问题
RQ1：现在代码注释实践状态是什么，问题是什么
- 82%人会写注意，81%在读没有注释的代码时感到困惑
- 69%和62%的人认为注释的缺失和笼统的注释是主要问题
RQ2：自动化代码注释工具对从业者有用吗？
- 80%认为值得且必要
- 78%认为这些工具可以更好帮助他们理解源代码
RQ3：从业者对自动化代码注释工具的期望是什么？
- 85%期望工具在函数级别上注释，信息包括 1）函数做了什么（功能）；2）如何使用方法；3）为什么这个方法存在
- 最需要注释的地方是复杂、棘手和非自解释的方法
- 生成的注释的最佳长度是2-3行。生成的注释应满足附加信息量、内容充分性和简洁性
RQ4:当前最先进的研究在满足从业者的需求和要求之前，其接近程度如何？
- 25篇论文，17个在函数等级生成注释
- 然而很少文章注释 “how to use” “why a method exists” 想你洗
- 大多数论文专注于测量生成的评论和人类撰写的评论之间的重叠N-gram，而这并不是从业者的首选
- 没有论文评估生成的评论中额外的信息数量，这是大多数从业者期待的
我们的研究旨在帮助研究人员考虑从业者的需求，以继续发展更好的代码注释生成技术，最终实现高采纳率和满意度。贡献如下
- 1. 采访了16位专业人士，并对720名从业者进行了调查，解释了从业者的期望，包括了他们对注释生成重要性的看法以及他们采用或不采用这些技术的门槛和原因
- 1. 我们回顾了过去10年在SE和AI顶级刊物上的论文，我们将当前的研究状态和从业者的需求进行了比较，并强调了下一步可以做什么满足从业者的需求

2 RESEARCH METHODOLOGY

研究有3个阶段
- 阶段1：与专业人士进行访谈，了解他们在代码注释方面的实践、面临的问题以及对代码注释生成技术的期望。
- 阶段2：通过在线调查来确认和扩展基于访谈得出的关于代码注释的结论。
- 阶段3：进行文献回顾，分析当前最先进研究在满足从业者需求和要求方面是否以及在多大程度上取得了成功。访谈和调查已获得相关机构审查委员会（IRB）的批准。

Stage 1：Interview

本阶段目标理解专业人员在软件开发中的注释实践和问题，以及他们对代码注释生成的期望
采访分为3部分
- 1. 参与者的背景信息
- 1. 开放问题：他们认为的好的或坏的代码注释
- 1. 讨论他们面对与代码注释相关的的实践和问题
数据分析：使用NVivo量化分析软件

Stage 2：Survey

设计

调研可以分为六部分
- 1. Demographics
- 1. Commenting Practices
- 1. Commenting Issues
- 1. Tool Importance:这部分给调查对象代码注释工具直接的描述，并询问他们如何看待这类工具的重要性，具体陈述如下：
  - (i) essential：我每天都会使用这个工具来帮助软件开发或代码理解
  - (ii) worthwhile：我会使用这个工具来帮助软件开发或代码理解
  - (iii) unimportant：我不会使用这个工具
  - (iv) unwise：这个工具会损害我或我的团队的生产力。
  - 然后，我们询问了从业者关于重要性方面的问题（例如，提高开发效率和代码可读性）
- 1. Practitioners’ Expectations
  - 从业者的期望，包括偏好粒度等级
  - 期望的注释内容，注释位置，不同注释等级对应不同长度的注释
- 1. Tool Adoption：询问受访者影响他们使用注释生成工具的因素，我们询问了以下因素
  - minimum Turing Test rate：自动生成的注释和人工注释的区别
  - maximum revised rate：最大修改率
  - minimum efficiency：生成注释用时
最后进行自由建议实践
我们也对另一些人询问了我们调查问卷的问题
- 1. 调查问卷的长度是否合适
- 1. 问题是否清晰
对中国参与者搞了中文

参与者要求

1. 通过IT公司的关系，获得598份回复
1. github仓库顶尖开源仓库，向2000名潜在开发者发送链接，获得137份回复

Stage 3：Literature Review

通过以下几个因素考虑技术的能力
- 粒度等级
- 注释什么
- 那里注释
- 评估指标

3 RESULTS

Finding 1：年轻从业者在读没有注释的代码时感到困惑的比例搞。软件项目中注释的质量和数量优先，很少有团队进行注释回顾
Finding 2：缺失注释和没有提供过多信息的笼统注释是最频繁的问题
Finding 3：80%受访者认为代码注释生成工具对他们有用。但这个发现不能证明大多数工具会有用，这表示代码注释生成工具不是无用的
Finding 4：方法级别的注释最被需要。小部分（28%）期望语句级别的注释
Finding 5：对于类级别的注释，功能和如何使用类是参与者期望自动化注释生成工具生成的最重要的信息。有着复杂逻辑和设计模式的类需要被好好地注释
Finding 6：对于方法级别的注释，功能，如何使用，输入和输出，设计原理是需要注释的重要信息。大部分参与者希望生成这样的信息。换句话说，注释需要从是什么，怎么用，为什么方面来。
Finding 7：对于语句等级的注释，大多数受访则会需要包括功能和设计原理的注释。
Finding 8：在3个维度上，工具生成2-3行的注释最佳
Finding 9：大多数论文生成了描述代码片段做什么的注释（功能和实现细节），少部分描述了如何使用和它为什么存在。考虑到需要被注释的代码片段的类型，大多数研究为所有类型的代码片段生成了注释，但是在对的地方生成注释比在所有地方生成注释更重要
Finding 10：现有工具（1行）和从业者期望（2-3行）的生成注释的行数有巨大区别
Finding 11：大多数论文专注于测量生成评论和人类编写评论之间的重叠N-grams，大多数受访者所并不偏好。所有研究都忽略了从业者最重视的附加信息量（即，除了从扫描源代码中容易获取的信息之外的量）

4 DISCUSSION

4.1 Implications 影响

Comment completion tools
Identifing where to write comments
Describing why a code snippet exists
Evaluation Criterion
Detecting inconsistencies between comments and source code
Checking if the source code is self-explanatory

4.2 Threats to Validity

从业者回答的问题可能不准确

5.1 Audomated Code Comment Generation

5.2 Studies on documentation practices

6 CONCLUSION AND FUTURE WORK

本文我们采访了16位找专家，调研了720名从业者，关于他们在注释实践中遇到的问题，以及他们对代码注释生成工具的期望。
- 从业者对注释生成技术研究很热情，期望工具能生成不同粒度的注释
- 从业者期望评论生成在评论内容、评论位置、评价标准、有效性和效率等方面满足要求。
我们也会比较当前研究状态中评论生成的能力与从业者对采用的期望，以识别差异。我们指出了SOTA研究的缺陷和为未来注释生成工具更好地被从业者采用的发展的路
未来研究应在正确的位置生成注释而努力而不是在所有地方。此外，未来研究应该更关注从业者重视的评估指标