APIContext2Com:Code Comment Generation by Incorporating Pre-Defined API Documentation论文阅读笔记

0. 写在前面的总结

APIContext2Com: 一种利用预定义API文档生成代码注释的方法. 该方法使用一个序列到序列的神经网络模型，结合了源代码、抽象语法树、API定义和API描述四种输入，来提高生成注释的效果和质量。
API文档的作用. API文档包括API的名称、参数类型和名称、功能定义和描述，可以提供有关代码功能的有用信息。作者认为，将API文档整合到模型中，可以帮助模型更好地理解代码的含义和目的。
API排名机制. 作者提出了一种基于参数相似度的排名机制，来筛选出与代码功能最相关的API，从而减少无关或干扰性的API对模型的影响。实验结果表明，选择合适数量的API可以提高模型的性能。
模型架构和细节. 作者详细介绍了模型的编码器和解码器的结构和原理，以及如何计算注意力权重和目标词的概率。作者还探讨了不同的循环神经网络变体（GRU和LSTM）对模型效果的影响。
实验设置和评估指标. 作者使用CodeSearchNet数据集中的Java部分进行实验，并使用BLEU，ROUGE-L和METEOR三种指标来评估模型生成注释与参考注释之间的相似度。作者还进行了人工评估来验证量化结果。
实验结果和分析. 作者将模型与四个最新的基准模型进行了比较，并在所有指标上取得了最好的结果。作者还分析了不同数量的API输入对模型性能的影响，以及API文档对生成注释质量的提升。作者通过两个案例研究展示了API文档如何帮助模型生成更准确和完整的注释。

1. motivation部分

Shahbazi等人在他们的研究中提出了一种名为APIContext2Com的新方法，通过整合预定义的API文档来提高生成代码注释的效果。作者认为，API文档可以提供有关代码功能的有用信息，帮助生成更好的注释。作者介绍了一种seq-2-seq模型，其中包括多个编码器，用于将不同类型的输入转换为目标注释。作者还开发了一个排名机制，用于排除非信息性API，从而过滤掉与代码功能无关或干扰性的API。实验结果表明，选择合适数量的API可以提高模型的性能。此外，Shahbazi等人发现，对于具有三个以上API的方法，API文档并不是很有用，并且会误导模型提供摘要。因此，他们开发了一个排名机制来计算每个API与给定方法之间的相似度，并计算每个API的分数。

为了实现这个目标，我们比较API和方法的输入参数，每有一个不同之处，就给API一个负分。这样，我们就可以确定哪些API更有可能为代码摘要提供有用的信息。在图3的例子中，await(long timeout, TimeUnit unit)排名最高，但其他两个API，getCount()、dispose()，因为它们在参数上有差异，每个API都会得到两个负分。根据包含的API数量的不同，它们在生成注释时的机会更小。

2. Proposed approach部分

2.1 model overview

编码器接收来自不同输入的四种不同类型的文本序列，包括代码片段、抽象语法树、API定义和API描述。编码器的架构包括两个单独的编码器和两组编码器，其中前两个编码器分别处理源代码和抽象语法树，后两组编码器分别处理API定义和描述。

代码被喂到到单个编码器中，如图2所示。编码器包含嵌入层和GRU层。我们将编码器应用于AST。首先，使用srcMl工具生成源代码的AST树表示，然后使用SBT方法[13]对其进行flatten处理。处理后的AST被用作纯文本序列来馈送编码器。

API描述/ API定义与代码/ AST不同。每种方法只有一个代码和一个AST，但每种方法都有一个API列表。因此，每个API都被馈送到一个编码器中，然后使用编码器的隐藏状态来馈送最终编码器。最终编码器的输出与代码和AST编码器的输出相同。正如我们已经提到的，我们定义了一个阈值，因此我们仅基于排名机制集成特定数量的API。接下来，为每个编码器计算注意力，类似于典型的编码器-解码器模型。对于AST和代码，计算每个标记的注意力权重，而对于API，则计算每个API的注意力分数。接下来，将编码器的隐藏状态连接起来并传递给全连接层，然后传递给解码器。

2.2 model details

每个编码器从不同的输入中接收一种文本序列，包括由代码表示的代码片段，由ast表示的平坦AST，由def表示的API定义序列和由des表示的API描述序列。代码和AST的编码器架构类似。我们考虑代码片段编码器来详细说明以下结构。首先，编码器将标记序列映射到标记嵌入中。然后，嵌入输出传递给双向GRU以提取上下文信息。 GRU框架被设计和优化以防止长期依赖问题[25]。在每个步骤中，GRU的隐藏状态定义如下：

ast也是类似的结果

API描述/ API定义与代码/ AST不同。每种方法只有一个代码和一个AST，但每种方法都有一个API列表。

由于每种方法都可以有多个API，这意味着有多个API定义和描述，我们将每个API映射到一个编码器，而不是像[23]中那样串联描述。我们考虑API的定义来详细说明流程。单个编码器处理每个单个API定义，导致每个API具有唯一的隐藏状态，如下所示：

进一步地，隐藏状态被拼接成一个序列，输入到一个最终的编码器中，得到一个表示整个API定义的单一隐藏状态。最终的编码器不包含嵌入层，因为输入已经是向量，所以不用再进行embedding操作了。它的公式如下：

相似的，api的描述也可以用相同的方法完成。

注意力机制帮助解码器在每个预测步骤中更有效地关注不同输入中的适当标记。例如，代码中的关键字return或set可以分别表示注释中的单词“get”或“update”。因此，评论中的不同部分可以与代码的不同部分相关联。为了计算目标标记yi的注意力权重，使用前一个标记的解码器隐藏状态h0i−1，如下所示：

其中a是线性模型，h’_i−1是解码器隐藏状态，αij表示在位置j处输入的代码和在位置i处的目标注释的相关性。此外，上下文向量被定义为输入的隐藏状态的加权和。

decoder旨在生成人类语言的最终注释。以下公式用于生成输出和时间步t的解码器隐藏状态：

其中，h’t−1表示前一个标记的解码器隐藏状态，yt−1表示前一个标记

decoder的初始隐藏状态是四个输入的最终编码器隐藏状态的组合。为了计算初始隐藏状态，将四个编码器的隐藏状态连接起来并传递到完全连接的层中。

其中 Wc， Bc都是可训练的参数

Context vector是上下文向量，可以理解为当前时刻加入注意力后的语义信息。

下一步，根据前一个标记、隐藏状态和上下文向量计算时间t的目标标记的概率。

接下来，基于前一步的token、隐藏状态和上下文向量来计算目标令牌在时间t的概率。这里的g表示的是softmax函数。

这里简单描述一下softmax函数,他可以将数值进行归一化处理，从而选出概率最大的结果进行输出。

2.3 Ranking System

如前所述，馈送给模型的API列表是基于排名系统的；这意味着我们可以对函数中使用的API进行排名，并将前n个排名最高的API馈送给模型。排名是基于函数和API参数之间的差异数量。设P = {p1，… pn}为函数参数列表，Mi = {mi1，… mik}为API_i（APIi在函数中使用）的参数列表。

Diff计算P和Mi之间的差异数量。这个分数是根据函数中使用的所有API来计算的。具有较高Si值的API是最高排名的API。

3. Experiments部分

3.1 Dataset

在这项研究中，我们使用CodeSearchNet [24]数据集来进行实验，包括训练和测试我们提出的模型以及运行基准模型。最近的许多研究都利用了这个著名的数据集来进行实验，特别是在代码注释生成方面[27, 28]。CodeSearchNet由来自Github仓库的不同数据集源组成。这些数据集是使用一个名为Libraries.io的工具收集的，该工具旨在识别具有更高有效性的项目。所有没有有效许可证的项目都已从最终数据集中删除。这个数据集包含六种不同的语言，包括Python, Javascript, Ruby, Go, Java和PHP。为了我们的研究目的，我们提取了数据集中的Java部分来运行实验。每一行数据包括一个完整的Java方法和相应的参考摘要，这些是本研究所需的。与[19]类似，我们在训练模型之前进行了一些预处理步骤。

token在camelcase（驼峰命名法：fileName、lineNumber，即第二个单词首字母大写）或snackcase(蛇形命名法：file_name、 line_number，即使用下划线进行连接)存在时被分割。此外，我们还从代码中删除了标点符号，并将所有token转换为小写。与[27]的研究类似，我们将代码和摘要的最大长度分别设置为256和64。我们删除了长文本的记录，其中使用截断代码无法生成AST，我们可能会丢失宝贵的知识。这个预处理步骤是必需的，因为本研究中的一些模型使用了AST，我们必须提供相同的条件才能进行公平的比较。数据集被分为训练、验证和测试，如表I所示。训练和验证集用于训练模型和选择最佳模型，而测试集用于评估模型。

3.2 API Documentation Extraction

作者使用爬虫程序，从Java文档工具包(JDK)下载API定义。API定义包含了所有参数的类型和名称。为了匹配方法中的API和下载的API上下文，作者首先提取了给定方法中的所有API。我们使用SrcML工具将源代码转换为AST表示。然后我们使用它来通过AST表示识别API。在将识别的API与爬取的API匹配后，作者提取了参数的名称和类型。

3.3 Experiment Setting

作者在PyTorch框架上实现了所提出的方法。为了训练模型，我们将嵌入和隐藏状态的大小分别设置为256和512。我们将批量大小和迭代次数（周期）设置为32和100。然而，如果在七次连续迭代中没有观察到改进，训练将停止。随机梯度下降被用作优化器，初始学习率的配置为0.1。为了减少过拟合的可能性，作者采用了多个具有0.2值的dropout层。模型在训练集上进行训练，通过验证集确定不同迭代中的最佳模型权重，最后在测试集上评估选定的模型。

4. Experient Results

4.1 Baselines

作者根据作者报告的最佳超参数运行了Rencos，AST-Attendgru，TL-CodeSum，DeepCom这些模型。请注意，作者没有选择像CodeBERT [27]和GraphCodeBERT [29]这样的预训练模型来进行结果比较，因为i)它们有一个不同的训练过程，即通过在大规模语料库上进行预训练来进行语言建模，ii)它们基于Transformer [30]架构，以及iii)它们是更大的模型，并且已经显示出更大的语言模型性能越好[31]。此外，类似的工作没有将它们与他们的方法[20, 21, 32]进行比较。由于包括这样的语言模型不是一个公平的比较，所以我们只将APIContext2Com与非语言模型的基于RNN [21]的方法进行比较。

Rencos [21] Rencos的作者提出了一种基于注意力的编码器-解码器模型，借助基于检索的摘要任务。他们通过检索相似的方法并将它们结合到模型中来改进模型。最初，模型在由代码和摘要对组成的训练集上进行训练。在测试阶段，该模型从训练集中检索出两个最相似的方法，根据语义和语法进行比较。代码和检索到的方法被编码，解码器通过融合输入生成最终的摘要。他们在他们的模型中包含了RNN的一种变体，即Bi-LSTM层。

TL-CodeSum [22] 介绍了一种基于GRU框架的序列到序列模型，它从不同但相关的任务中学习API知识。事实上，他们开发了一种代码注释生成模型，借助从API序列摘要模型转移过来的知识。后者旨在建立API序列和相应摘要之间的映射。在API序列摘要任务中学习到的知识被转移到代码注释生成模型中，以提高模型的性能。

AST-AttendGRU [19] 提出了一种带有注意力机制的GRU编码器-解码器代码注释生成模型。他们将扁平化的AST序列结合到模型中，以有效地捕捉代码片段的语法信息。他们利用两个不同的编码器，一个处理代码片段令牌，另一个处理AST令牌。这样，代码片段的语义和语法信息都可以考虑到，以改善生成的注释。

DeepCom [18] DeepCom提出了一种将抽象语法树结合到模型中的新方法。他们设计了一种树遍历技术，即基于结构的（SBT）遍历，能够有效地捕捉源代码的语法信息。此外，他们使用SBT将AST树进行flatten处理，并以文本序列的形式将AST结合到模型中。

RQ1: APIContext2Com 与其他模型的对比

在这个研究问题中，作者比较了APIContext2Com模型提出的方法和其他模型进行对比。结果如表II所示。APIContext2Com优于所有其他模型，并将最接近的基线Rencos提高了1.88 (8.24%)，2.16 (17.58%)，1.38 (18.3%)，0.73 (14.17%)，1.58 (14.98 %)和1.9 (6.92 %)的BLEU1，BLEU2，BLEU3，BLEU4，METEOR，ROUGE-L分数。这种改进是由于从API上下文中提取信息，这些信息是通过选择相关的API来捕获的。此外，采用适当的架构来分别处理每个API对于捕获信息也有重要影响。

Rencos模型在其他basleine模型中获得了最高的分数，这是合理的，因为它们通过检索相似的方法来整合外部知识。外部知识以及利用AST结构信息使Rencos优于其他模型。接下来的结果属于TL-CodeSum和AST-AttendGRU。同样，TL-CodeSum结合了API来改善摘要生成。然而，结果并不像预期的那么高，它几乎与包含代码和AST的AST-AttendGRU相似。原因是它们没有使用任何额外的信息，只使用了API名称。这些名称已经存在于源代码中，并且在源代码处理过程中已经处理了信息。因此，只添加API名称可能无助于增加更多的知识。在所有模型中，DeepCom获得了最低的分数。我们假设它们未能有效地捕捉模型的词汇信息，因为源代码的token没有直接用于模型中。

RQ2: The Effect of Ranking Mechanism on the Model’s Performance and Best Number of APIs to Include in APIContext2Com

由于一些API不仅没有帮助，而且会产生误导，所以在本节中，我们进行了一些额外的实验，以发现最佳的API数量。正如前面所讨论的，我们使用一个基于点数的系统来根据它们与主方法的相似度来对API进行排名。因此，排名系统使我们能够选择并包含前n个排名最高的API，并丢弃其余的API。但是，我们应该决定要包含这些API的数量（即n）。我们进行了一些实验，包括不同数量的API，最终发现了最佳的API数量，从而获得了最高的平均分数。我们尝试了2、3和4个API，如表III所示，使用3个API的模型获得了最高的分数。1选择少于三个API会使性能下降约0.7 BLEU-1。2同样地，包含超过三个API会降低性能，使用4个API时，我们的性能下降了约0.3 BLEU-1。表III的最后一行显示了当不使用排名系统而是考虑所有API时的分数。3在这种情况下，与3个API相比，性能下降了0.8分。4我们得出结论，根据所提出的排名系统过滤API有助于模型生成更高性能的注释。 有趣的是，虽然包含在模型中的最佳数量是前3个API，但包含所有API或其他数量的API与3个API有相当的结果。这证实了除了排名系统之外，包括API上下文和所提出的架构也有助于模型捕捉相关信息。这一点将在下一个RQ中详细探讨。

RQ3: Effect of Incorporating API Context and Distinct RNN Variants (GRU & LSTM)

在这个研究问题中，作者探索了提出的模型的简单版本，以更好地理解整合API上下文的效果。简单模型指的是提出的模型排除了API上下文，只接收源代码和flatten处理后的AST作为输入，显示为APIContext2Com-APIcontext。表IV的第一行表示了APIContext2Com-APIcontext与GRU架构的性能。1APIContext2Com在API上下文中改善了简单模型的结果，分别为BLEU 1-4、METEOR和ROUGE-L的≈ 3.47、4.6、3.47、2.16、2.92、6.53。
因此，整合API的外部知识的效果是不可忽视的，它可以为模型提供有价值的信息来预测更好的评论。 我们进一步探索了不同框架，RNN变体，通过使用LSTM复制实验的效果。作者使用LSTM替换GRU，并保持我们模型的其他组件不变。表IV中显示了用于模型名称下标的架构。有趣的是，简单的LSTM模型，APIContext2ComLSTM-APIcontext，与APIContext2ComGRU-APIcontext相比有稍微高一点的性能。但是整合API会使GRU变体的结果比LSTM版本的模型更好。考虑到BLEU-1作为一个代表性指标，APIContext2ComGRU-APIcontext和APIContext2ComLSTM-APIcontext分别得分为21.23和21.87。添加API上下文，APIContext2ComGRU和APIContext2ComLSTM分别达到24.7、24.23；意味着相对于简单的GRU和LSTM模型分别提高了3.47、2.36,4。这可能与GRU框架能够更有效地捕捉API信息有关，因为当添加API上下文时，这种架构有更多的改进。

4.2 Human evaluation

在这项研究中，我们使用了三种度量标准，即BLEU、ROUGE-L和METEOR，来衡量模型生成的注释和参考注释之间的相似度。然而，它们有时无法正确地计算相似度，因为它们只考虑了文本而不是语义的相似度。因此，我们进行了人类评估，以确认度量标准所达到的定量结果。 为了进行人类评估，我们使用了亚马逊机械土耳其(AMT)网站。这是一个众包应用，可以将过程或任务分配给不同的远程工作者。任务被定义为HITs(人类智能任务)的形式，远程个体被付费来执行它们。我们定义了一个任务，比较四个模型生成的注释与参考注释之间的相似度。这四个模型是我们提出的模型和三个最好的基线模型，包括Rencos、TL-Codesum和AST-attendGRU。与以前的研究[23]类似，我们从测试集中随机选择了100个样本，每个样本包含参考注释和三个生成的注释。评估者（远程工作者）需要对每个生成的注释给出一个5点量表的分数，其中1表示生成的注释和参考注释之间的语义相似度最低，5表示最高。为了获得更准确和一致的结果，每个任务由三个不同的评估者评分，并计算平均值作为最终值。

评估者首先通过提供例子来进行标准的学习。在测试过程中，生成注释的模型的名称被隐藏起来，以提供一个公平的比较。评估者提供的结果分别是2.53、2.39、2.11、1.81，分别对应APIContext2Com、Rencos、AST-attendGRU、TL-Codesum。APIContext2Com相比Rencos、AST-attendGRU和TL-Codesum分别提高了6%、20%和39%。这个结果证实了APIContext2Com生成的注释比其他方法更接近真实的注释。

5 Discussion

5.1 Score Distribution and Effect of API Context

=> API Context 在分数上的效果和贡献

在本节中，我们分析了模型在记录级别的性能，以及将API文档整合到模型中的效果。为了简单起见，这部分的计算只考虑了BLEU-1。 图4，条形图，显示了APIContext2Com的BLEU-1分数的分布。有相当一部分数据，约47%，分数低于20。这并不令人惊讶，因为有很多样本，输入不能为模型提供任何有用的信息来预测注释。这可能是由于三个主要原因。首先，代码没有写得易读，比如命名不佳。其次，代码是正确的，甚至模型生成了合理的摘要，但参考注释可能并不总是代表代码的功能，比如技术债务注释[37]。第三，代码和注释都是好的，但模型在训练过程中没有看到足够多的相似例子。大约20%的样本分数分散在20到30之间，这是平均分数。超过32%的样本获得了高于30的分数，有趣的是，有时接近100。当我们调查这些情况时，我们发现了很多高分的例子，其中有一个API有一个注释，它与参考注释非常相似。

图4中的饼图探索了将API文档添加到简单模型APIContext2Com-APIcontext（即只有代码和扁平化AST作为输入）的效果。1饼图比较了APIContext2Com-APIcontext和APIContext2Com模型在记录级别的分数。两个模型对约29%的样本生成了相似的评论。这是合理的，因为这些样本大多不使用任何API。超过46%的情况，最高比例，通过APIContext2Com获得了更好的分数。这些是API文档主要有用和相关的样本。剩下的样本是那些通常携带一些API的样本，其中文档有些误导性，而APIContext2Com-APIcontext具有更高的分数。

图4中的饼图探索了将API文档添加到简单模型APIContext2Com-APIcontext（即只有代码和flatten AST）的效果。1饼图比较了APIContext2Com-APIcontext和APIContext2Com模型在记录级别的分数。两个模型对约29%的样本生成了相似的评论。这是合理的，因为这些样本大多不使用任何API。超过46%的情况，最高比例，通过APIContext2Com获得了更好的分数。这些是API文档主要有用和相关的样本。剩下的样本是那些通常携带一些API的样本，其中文档有些误导性，而APIContext2Com-APIcontext具有更高的分数。

5.2 Code and Comment Length

评论生成模型的一个常见分析是，随着代码长度或评论长度的增加，BLEU分数的变化。图5展示了APIContext2Com和两个最好的基线模型，Recos和AST-AttendGRU的BLEU-1分数。1基线模型是为了比较不同模型遵循的趋势。图中显示了代码长度以20为步长，评论长度以3为步长的平均分数。例如，在右图中，评论长度为6的分数反映了评论长度在3到6之间的平均分数。平均而言，APIContext2Com比其他模型有更高的分数。2图表显示了APIContext2Com在不同长度上的稳定改进。然而，随着代码或评论长度的增加，所有模型的分数都有所下降。对于代码长度，在所有模型中，APIContext2Com有一个稳定的下降，当长度超过140时有一个轻微的正斜率。相反，Rencos有一个波动的趋势，AST-AttendGRU的性能随着代码长度的增加而下降。对于评论长度，所有模型都遵循类似的趋势。性能在长度为9时增加，在这个长度之后下降。APIContext2Com在几乎所有评论长度上都比Rencos和AST-AttendGRU有更高的分数。

5.3 具体的例子

在本节中，我们展示了两个例子，说明了API上下文如何提高预测注释的质量。第一个例子展示了API描述的效果，第二个例子展示了API定义的优势。在图6中，例子1，由简单模型APIContext2Com-APIcontext生成的注释“Creates a file ”与参考注释相比，解释了有限的信息。然而，APIContext2Com根据参考注释预测了一个更准确的注释。快速查看这个方法中使用的API及其各自的注释，可以发现API2和API3，createNewFile和setLastModified，有非常相似的描述与参考注释。图中绘制的热图表示了APIContext2Com对API描述的注意力。颜色越浅，注意力越高。如图所示，在预测“create new File”这几个词时，APIContext2Com更多地关注了第二个API，在预测“set the last modified time”这几个词时，也关注了第三个API。这证实了我们的假设，即当正确选择时，API描述可以帮助生成注释。

在图7中，显示了第二个例子，其中由APIContext2Com-APIcontext模型生成的注释没有包含一个关键词“开始”，而APIContext2com在生成的注释中添加了这个词。快速查看代码片段可以发现，没有类似于“开始”的词。因此，预期从APIContext2Com-APIcontext缺少这个词。然而，探索这个方法中的API显示，在API 2的定义中有一个参数名是 beginIndex，热图证实了模型在预测“begin”时关注了API2。