【综述笔记】 A survey of automatic generation of source code comments Algorithms and techniques

A survey of automatic generation of source code comments Algorithms and techniques

ABSTRACT

代码注释存在问题：代码注释有助于程序理解，然而因为非常耗费精力、程序员缺乏相关知识，以及其他因素，代码注释常常短缺，甚至与源代码不匹配。

为此，一直有研究人员在关注代码注释的自动生成问题。

本文作为对自动代码注释研究的综述，做了以下工作：1. 对注释自动生成存在的挑战和研究框架进行总体分析。2. 总结代表性算法的分类、设计原则、每类算法的优缺点。3. 提供对生成注释的质量评估的概述。4. 总结自动代码注释今后的研究方向。

1 INTRODUCTION

代码注释有助于算法/程序理解，但编写耗时耗力，为此人们在自动生成代码注释方面下了很多努力。如：用长的描述性名称定义标识符，以实现自动代码注释，但反而使代码理解更困难。

现有的方法大多基于机器学习或信息检索技术，代码注释生成的框架主要有三部分：1. 数据准备，为注释系统准备数据；2. 源代码表示，捕获源代码的结构和语义，如结构、词汇、语法、语义、上下文、调用关系和数据依赖性等信息；3. 文本生成，基于源代码中提取的信息，生成自然语言描述。

另一个重要的研究问题：生成代码注释质量的评估，这是评价注释生成算法是否高效、有效的重要指标。因此，设计合适的代码注释质量标准是当前面临的挑战，评估质量包括算法的比较和验证。

代码总结（code summary）类似于代码注释，可以视作一种特殊的自动代码注释工作。

本文目标：(1) 为研究人员提供一份自动注释生成的代表性算法目录，使新研究人员对目前最先进的自动代码注释算法有较好的了解; (2) 总结现有研究的主要挑战和局限性。

首先介绍动机、分析存在的主要问题、描述工作流程。然后讨论3种主流算法，指出潜在发展趋势。总结注释质量评估的工作，提出发展方向。调查生成代码总结的工作。

2 OVERVIEW OF AUTOMATIC GENERATION OF CODE COMMENTS

A. PROBLEM STATEMENT

代码注释自动生成关注于把编程语言转换为自然语言。注释可以描述功能、代码设计意图、程序理解、程序功能以及相关参数的含义。

B. CHALLENGES OF AUTOMATIC CODE COMMENTING AND RESEARCH FRAMEWORK

如图1，代码注释自动生成的大致过程基本分为3块：

1. 数据收集，这些数据用于训练、验证和测试模型、提取代码和相应的注释，或者提取注释生成系统所需的特定规则。数据通常从开源项目中爬取，如Stack Overflow。
2. 生成注释，这一步分解为两个子任务：(1) 表示源代码；(2) 生成文本。
3. 质量评估，对生成的注释进行质量评估，设计实用、客观的质量评估标准，比较不同算法的性能和注释生成质量。

1) CHALLENGES OF AUTOMATIC CODE COMMENTING

挑战：编程语言在本质上不同于自然语言。

代码和注释的区别：(1) 源代码包含大量关于类、方法和方法参数的信息，同时有许多嵌套结构和复杂的调用关系； (2) 自然语言编写的注释是非结构化的，形式上自由表达。

因此，自动代码注释面临以下两个挑战：算法和质量评估。

a: CHALLENGE 1: AUTOMATIC CODE COMMENTING ALGORITHMS

挑战1：代码注释自动生成算法

当前已有多种自动或半自动的代码注释生成算法，主要分为以下三类：(1) 基于信息检索；(2) 基于深度神经网络；(3) 其他代码注释自动生成算法。算法的两个主要问题包括源代码表示和注释文本生成。

SOURCE CODE MODELS

核心问题：源代码模型 ——如何表示源代码。

源代码模型分类：抽象语法树、解析树、token上下文、控制流图形(CFGs)、数据流等

用于自动注释的源代码模型分为三类：(1) 基于token，主要从源代码中提取keywords、topic等token。代码表示为普通的文本，常表示为bag of code tokens(BoT)，或者characters or bag of words(BoW)。主要应用在基于信息检索的注释算法。(2) 基于语法。代码表示为abstract syntax trees(ASTs)。主要应用在基于神经网络的注释算法。(3) 其他的源代码模型，以适合后续流程的形式表示代码，如Software Word Usage Model (SWUM)。

最后，仍然缺少一个可以表示各种信息的组合模型，如词法、语法和源代码结构。

TEXT GENERATION

难点：从源代码生成自然语言文本

前提： 从代码中准确提取信息

当前的文本生成方法可以分为三类：(1) 基于规则，人为设计规则或自然语言模板。(2) 基于生成，通过解码器生成文本。(3) 基于检索，从语料库中检索已有注释来生成文本。

b: CHALLENGE 2: COMMENT QUALITY ASSESSMENT

挑战2：注释质量评估

注释质量评估存在两个主要问题：(1) 用于验证和测试注释生成算法的数据集的统一。(2) 评估标准的选择。

UNIFICATION OF DATASETS FOR VERIFYING COMMENTING ALGORITHMS

目前，已有的研究利用的是不同的数据集来测试算法，使得测试结果和算法性能的比较变得困难。因此，统一的数据集十分重要。

SELECTION OF EVALUATION CRITERIA FOR QUALITY ASSESSMENT OF CODE COMMENTS

现有工作中代码注释的质量评估标准因注释类别的不同而不同：

从函数的角度来看，注释可以分为描述性注释、摘要注释、条件注释、调试注释和元数据注释等。

即使在同一类别中，不同的自动注释生成技术也采用不同的注释评估标准。因此，设计和制定合适的评注质量评价指标对促进代码评注自动生成的研究具有重要意义。