原文连接：点此位置
来源：The Journal of Systems & Software，2020

一、背景和Idea

1. 背景

现有的自动代码注释生成技术是基于注释的代码段已被识别的假设，因此要求用户提前提供代码段。给定源码，能否自动确定在哪里进行注释？为解决这个问题，作者提出了一种新的方法：CommtPst，可以在源码中自动找到合适的注释位置。

2. idea

由于注释与代码的语法和语义密切相关，作者先采用neural language model（word embeddings）来捕获代码语义信息，并分析抽象语法树（AST）来获取代码语法信息。然后，使用Bi-LSTM从语法和语义的角度来建模代码语句的逻辑依赖关系，并学习代码序列上的注释模式。

二、论文贡献

1. 挑战

主要挑战是注释的地方可能位于低耦合的代码语句中，如case2中的注释，与下面代码片段没有耦合相关性，因为这些代码语句一起实现初始化。因此，注释可以出现在不同形式的代码语句上，并且很难通过简单地考虑代码耦合相关信息来识别注释的位置。case1和case2显示了两种典型的注释模式，这些注释通常添加在控制语句和变量定义之前。还有一些其他的注释模式，比如多循环代码段，通常也需要注释来更好地理解。

2. 贡献

（1）CommtPst可以在生成代码注释前有效识别恰当的注释位置。
（2）提出使用LSTM建模代码语句之间的逻辑相关性，以进一步确定源代码中的注释位置。
（3）通过实验对比，综合评价的结果证明了论文的注释位置预测方法的可行性和有效性。

三、主要步骤

整体分为训练和预测两个阶段，前者从注释良好的源码中构建一个预测模型。后者则使用该模型确定源码中恰当的注释位置。步骤如下：

• 分析注释良好的源代码，并从源码中识别注释实例。每个代码行都对应于一个标签，总共有两个标签，分别对应于“已注释”和“未注释”。
• 提取每条代码的特征。特性是代码语句的各种可量化特征，可以区分需要注释的代码语句。论文提取了两种特征：代码的语法特征和语义特征。为了使LSTM利用这两种类型的特征并更具表达力，作者用提取的代码语法和语义特征构建了一个统一的向量表示。
• 将两种特征提取和融合后，构建了训练集，并在训练集上建立了一个预测模型。
• 将一个方法的整个代码语句作为预测模型的输入。对于该方法中的每条代码行，先提取在模型构建阶段的语法和语义特征。再将特征输入到预测模型中。此步骤将输出与被注释或未被注释的代码语句相对应标签的预测结果。最后，将“注释”代码语句返回到方法的源代码，便可得到此方法要注释的位置。
  
  

四、数据采集

1. 项目选择

作者调研了GitHub的十个大型开源软件项目：Ant、ANTLR、ArguUML、cooQAT、JDT、JHotDraw、JabRef、JFreeChart、Lucene和Vuze。每个项目都包含超过一万条用Java语言编写的代码语句，利用用这些项目构建数据集。

2.数据集构建

（1）注释类别
源码中使用的注释分为两种：header comment & internal comment

header comment出现在类或方法声明之前。internal comment与一个或多个代码语句相关联，它们通常在这些相关的代码语句之前，或位于代码语句的后面（在同一行上)，并且只服务于当前的代码语句。因为header comment只能出现在类或方法声明之前，所以不需要预测其位置。因此，CommtPst仅用来预测internal comment的位置。
（2）数据标注
对于方法中的每个代码行，如果其中有注释或其前一行是注释，则代码行将标记为“注释”；否则，标记为“未注释”。带有“注释”标签的代码语句对应正实例，带有“未注释”标签的代码语句对应负实例。
（3）数据预处理
主要是去除无效的注释实例，对原始的“注释”代码语句应用了一系列预处理规则，有如下两种：

（1）代码行是测试代码行或由开发人员更改的废弃代码，如：
          //if(obj.getName()==null)
（2）由工具自动生成的注释，如：
          //自动生成的捕获块。

• 对于自动生成的注释，可以识别关键字（如“自动生成”）以去除。
• 对于被注释掉的代码语句，使用静态分析方法来识别它们。即对每个注释，先删除其注释符号，然后使用AST分析器来解析“注释”。如果可以将“注释”解析为语法token，如IfStatient，则“注释”将标识为注释代码行。
  
  

五、代码特征学习

1.代码语法信息提取

假设：开发人员在源代码中选择注释位置与的语法密切相关。
方法：通过分析程序的AST来获取代码语法信息。作者使用Eclipse JDT来提取代码的AST。代码语法细分为96种类型，每种类型由语法标记表示(e.g., IfStatement, ForStatement, ReturnType, VariableDeclaration, etc.)。作者从源代码语句的AST中解析每个代码语句的语法结构。对于AST中的每种类型的语法 token，首先通过解析AST得到源代码中的开始行和结束行，然后计算每个代码行所涉及的语法 token。提取流程如下图：

在将上述方法用于源代码后，可以获得每个代码行的语法token。根据代码语句的顺序，将这些语法token组成一个语法语料库，用于在训练阶段捕获注释位置和代码语法信息之间的关系。

2.代码语义信息提取

必要性：源代码类似于自然语言，因为其由包含大量代码语义的标识符组成。代码语义信息已有效应用于许多领域，如software traceability recovery , linkable knowledge mining , API mining , bug reports retrieval等。因此作者自然也想到通过代码语义信息来表征注释位置。
方法：从源代码的文本元素中提取代码语义。显然，并非所有文本元素对于保留代码语义都是有用的，有的甚至会弱化代码语义，因此作者采用了一系列规则来提取代码语义：

（1）将驼峰形字母的单词分成单个单词，如：
         ‘getFirstName’ is divided into ‘get’, ‘first’ and ‘name’.
（2）过滤掉源代码中的停止词，如：
         ‘and’, ‘the’, ‘an’等。
（3）过滤掉数字或单个字母的单词，如：
         “n”、“i”、“0”等。
（4）为减少整个语料库中的词汇量，对文本元素使用了词干分割技术，并将不同时态的动词转换为其原始形式。

3.特征融合

方法：基于skip-gram结构的word2vec模型。由于语法信息由语法token表示，而语义信息以文本元素表示，因此很难直接融合这样两个以不同方式表达的特征。论文通过将这两种表示映射成共享空间的向量，构建了一个统一的语料库。具体做法如下：
（1）语料库的构建

对于每个代码语句，随机打乱其语法token和文本元素，并将打乱的结果添加到语料库中，如上图所示。这样做的目的是打破语法token和文本元素的固定位置。
（2）word2vec
论文采用skip-gram结构的Word2Vec模型构建包含语法结构和语义信息的向量，关于word2vec的知识可参考此处[1]，《理解 Word2Vec 之 Skip-Gram 模型》[2]，这里不展开。利用word2vec模型，每个单词都被转换为一个固定长度的向量。然而，由于不同的代码行有不同数量的语法token（或文本元素），如果简单地连接代码行中所有单词的向量，就很难为代码行保持固定长度的向量。通过对所有向量进行平均，将代码语句转换为向量表示。

4. Bi-LSTM

源代码可以看作是顺序数据，因此作者尝试使用RNN网络利用代码语法和语义信息对源代码上的注释模式进行建模，并进一步预测源代码中的注释位置，最终选择的模型是Bi-LSTM。LSTM是NLP较为常用的模型，原理可参考《人人都能看懂的LSTM》[3]这里不再展开。

网络通过考虑其上下文代码语句的语法和语义信息来计算每个代码语句的注释概率。训练目标是最小化代码语句的真实标签X和预测标签Z的交叉熵误差：

六、实验设置

1.数据选择和超参数设置

（1）注释方法（函数）阈值设置
方法代码行数的多少影响着内部注释的数量，作者通过统计发现，当代码的行数为5时，只有不到四分之一的方法需要注释，所以选择了5作为阈值来选择这些方法。从数据集中过滤掉了少于5行代码的方法后，得到了14,942个方法。为了更好地学习和预测评论的位置，随机选择了2000个具有完全没有注释的方法添加到数据集中，共有获得16,942个方法，按照约8：1：1的比例划分训练集、验证集和测试集。
（2）Bi-LSTM参数设置
根据统计，数据集中大约95%的方法的代码行不到50行,因此将Bi-LSTM网络的time step设置为50。少于50行的方法片段用零向量来填充，超过的则截断额外的代码行。训练的batch size为60，在输入层和输出层间添加一个隐藏层，维度为256。

2.评估指标

The precision (PRC)
recall (REC)
F-measure (F-MEASURE)

3.结果分析

• RQ1: What is the accuracy of CommtPst in predicting commenting positions?
• RQ2: What are the impacts of structural and semantic features on the accuracy?
• RQ3: Does the method size (i.e., code amount) affect the accuracy of CommtPst?
• RQ4: Does the number of comments per method affect the accuracy of CommtPst?

RQ1: Prediction accuracy

• 作者在之前的工作中提出了一种传统的机器学习方法（CommentSuggester）来预测注释的位置，与这篇文章的方法进行了对比，对比结果如下：
  
• 为衡量word2vec的重要性，对比了其他一些word representation technique和不同的深度学习方法，结果如下：
  
• 使用不同随机种子划分数据对结果的影响，如下：
  
  总之，Bi-LSTM与word2vec结合，可以获得注释位置预测的最佳精度。

RQ2: Features choice effect

• 不同的代码特征（即语法特征和语义特征）对预测精度的影响，无疑，结合有最佳精度：
  
• 为了让每条代码语句保留一个固定长度的向量，论文使用向量取平均的方法，此外还考虑了求和方法（即相加所有向量）和最大化方法（即最大池化，它只保持每个向量的最大值），比较结果如下：

RQ3: Code amount effect
代码量在5到50行范围的方法数占总方法的94%以上，因此论文主要关注CommtPst代码行在此范围内的方法上的性能。为了评估代码量的影响，对具有不同代码行的方法的数据集应用CommtPst，结果如下：

结果表明，当代码行数在5到50之间时，该方法的代码行的变化对CommtPst的性能有一定的影响，但影响有限（ps：波动怎么觉得还是有点猛）。
RQ4: Comment amount effect
方法段可能涉及一条注释或多个注释。为了评估CommtPst对涉及不同注释数量的方法的影响，根据注释量将这些方法分类为不同的子集，由于涉及少于或等于4个注释的方法占总方法的81%以上，因此作者主要关注CommtPst对注释数量在此范围的方法的性能。结果如下：

七、讨论：FN is real FN?

1.FN is real FN?

召回结果表明，CommtPst实现了一些假阴性实例。也就是说，CommtPst在把一些无需注释的位置判定为需要注释的位置。为了验证假阴性实例是否真的不需要注释，作者定性地与开发人员分析了一些假阴性实例，并询问开发人员这些位置是否应该进行注释。作者随机选择了100个由CommtPst识别的假阴性实例，请了5个资深的程序员进行验证，如果程序员觉得在假阴性实例中应该添加注释，要求程序员给出理由。这5个程序员独立地完成了他们的验证。结果显示，有32个假阴性实例他们一致认为应该添加注释，假设观察到的32%的完全一致的评论建议率是一致的，那么，论文检测到的32%的FN实例实际上应该是TP实例，修正过程和结果如下：

资深程序员给出的原因：

• 最共同的原因是代码逻辑复杂
• 其次是糟糕的命名风格

2.语法token与文本元素是否应该打乱

构建语料库时，作者随机打乱每个代码语句的语法token和文本元素，并将打乱的结果添加到语料库中。为验证这个做法的有效性，与无打乱的策略进行对比，结果如下：

结果表明打乱确实有助于提高精度，论文给出的解释如下：

Word embedding挖掘语法token和文本元素的并发性关系。如果不打乱语法token和文本元素，Word embedding可能很难在固定的窗口大小中挖掘语法token和文本元素的整体关系，所以可能无法捕获语法token和文本元素中具有类似含义的术语。而打乱后，Word embedding可以有效地揭示固定窗口中语法token和文本元素之间的整体关系。因此，打乱后的单词更容易表达具有相似意义的语法token和文本元素。（个人觉得有点像DQN的Experience replay的味道，打破数据的关联性）。

八、相关工作

这部分内容感觉也挺有参考价值，所以记录下来，方便自己以后查看。

1. Source code commenting practices

据作者了解，关于评估代码评论质量问题的研究最早可以追溯到20世纪90年代，这部分主要谈到两方面内容：
（1）注释评估指标

• Oman and Hagemeister (1992)[4] and García and Alvarez (1996)[5]通过评估软件系统中代码注释的比例衡量代码注释质量。
• Steidl et al.(2013)[6]使用决策树对代码注释进行分类，并通过四个指标来评估代码注释的质量，如实用性和完整性等。
• Khamis et al. (2010)[7]提出了一种叫做JavadocMiner的工具，通过一系列简单的启发式算法来评估代码注释的质量，如代码和注释之间的关联、注释所用的语言等。

（2）代码注释生成

• Wong et al.（2015)[8]提出了一种从堆栈溢出挖掘大规模问答数据自动生成代码注释的新方法。
• Wong et al. (2015)[9]应用 code clone检测技术，在软件存储库中发现类似的代码段，并用现有的注释来描述类似的代码段。
• Sridhara et al. (2010)[10]提出了一种自动为Java方法生成描述性注释的新技术。
• Moreno et al. (2013)[11]提出了一种自动为Java类生成可读注释的技术。
• Iyer et al. (2016)[12]使用LSTM模型为c#代码片段设计了一种代码注释自动生成方法。
• Allamanis et al. (2016)[13]使用卷积神经网络为代码片段生成短文本描述。
• Hu et al.[14]从AST中获取结构和语义信息，将其转换为序列信息，然后使用机器翻译模型将代码转换为注释。
• Hu et al. (2018)[15]考虑了代码API信息，这进一步提高了代码注释生成的准确性。
  现有的大多数注释自动生成工作都是对方法的摘要，但是当关注方法内部的注释时，现有的工作就会变得不适用，因为不知道该在哪里添加注释。所以需要使用一个预测源代码中注释位置的工具，也就有了作者一系列的研究。

2.Applying deep learning to source code analysis

• Mou et al. (2016)[16]设计了一个基于AST的卷积神经网络，此网络对程序的AST执行卷积操作，使程序中包含的结构信息更加突出。
• White et al. (2016)[17]用深度学习方法来学习code clone检测中的语法和语义信息。
• (Jiang et al., 2007[18];Gabel et al., 2008[19])将AST转换为完整的二进制树。
• Guo et al. (2017)[20]提出了一种利用 word embedding和递归神经网络模型来生成跟踪链接的跟踪网络架构。
• Gu et al.(2016)[21]用RNN编解码器生成API使用序列，还提出了一种名为CODEnn的深度神经网络，它学习源代码和自然语言查询的统一向量表示，以便根据其向量检索与查询相关的代码片段。
• Xu et al. (2016)[22]用CNN来预测开发人员在线论坛中的语义可链接知识。
• Lin et al. (2018)[23]用Bi-LSTM检测软件中的安全漏洞。
• Wang et al. (2016)[24] 用深度学习方法自动学习程序语义和软件缺陷之间的映射。
• Zhang et al. (2019)[25]提出了一种基于ASTNN的源代码表示方法，其将每个大AST分解为一系列小语句树，通过捕获语句的语法信息将语句树编码为向量，解决了大型AST引起的长期依赖问题。

九、对CommtPst有效性的威胁

1.评估指标的合理性

因为论文研究的问题可以视为一个二分类问题（代码语句的注释与否），使用传统的评价指标（ PRC，REC，F-MEASURE）可以评估CommtPst的有效性，所以选用这些指标较为合适。

2.模型的泛化能力

这个威胁是比较大的，因为CommtPst所用的项目源码都是Java，当应用于由其他语言编写的项目时，如C、C++、Python等可能效果不太行。未来需要分析更多由其他语言编写的项目来减轻这种威胁。

3.注释的质量

论文数据集选用的项目不可避免地会包含一些质量差的注释（尽管已经采取了一些过滤机制）。所以需要进一步研究这些项目的注释质量以减轻这一威胁。

十、总结

提出了一种识别源码中合适注释位置的新方法CommmtPst。为了确定源代码中的注释位置，提取了两种特征类型——代码语法和语义特征。然后用深度学习技术学习基于这两种特征的注释模式。实验结果证明了CommmtPst的可行性和有效性。在未来将进一步考虑CommtPst和代码片段自动注释生成的结合。

参考文献：

[1]http://zh.gluon.ai/chapter_natural-language-processing/word2vec.html
[2]理解 Word2Vec 之 Skip-Gram 模型，https://zhuanlan.zhihu.com/p/27234078
[3]人人都能看懂的LSTM，https://zhuanlan.zhihu.com/p/32085405
[4]Oman, P., Hagemeister, J., 1992. Metrics for assessing a software system’s maintainability. In: Proceedings Conference on Software Maintenance 1992. pp. 337–344.http://dx.doi.org/10.1109/ICSM.1992.242525
[5]García, M.J.B., Alvarez, J.C.G., 1996. Maintainability as a key factor in maintenance productivity: A case study. In: Proceedings of the 1996 International Conference on Software Maintenance. In: ICSM ’96, IEEE Computer Society, Washington, DC, USA, 87–.
[6]Steidl, D., Hummel, B., Juergens, E., 2013a. Quality analysis of source code comments. In: 2013 21st International Conference on Program Comprehension, ICPC. pp. 83–92. http://dx.doi.org/10.1109/ICPC.2013.6613836.
[7]Khamis, N., Witte, R., Rilling, J., 2010. Automatic quality assessment of source code comments: The javadocminer. In: Proceedings of the Natural Language Processing and Information Systems, and 15th International Conference on Applications of Natural Language To Information Systems. In: NLDB’10, Springer-Verlag, Berlin, Heidelberg, pp. 68–79, http://dl.acm.org/citation.cfm?id=1894525.1894535.
[8]Wong, E., Liu, T., Tan, L., 2015. Clocom: Mining existing source code for automatic comment generation. In: 2015 IEEE 22nd International Conference on Software Analysis, Evolution, and Reengineering, SANER. IEEE, pp. 380–389.
[9]Wong, E., Yang, J., Tan, L., AutoComment: Mining question and answer sites for automatic comment generation, in: Ieee/Acm International Conference on Automated Software Engineering, 2014, pp. 562–567.
[10]Sridhara, G., Hill, E., Muppaneni, D., Pollock, L., Vijay-Shanker, K., 2010. Towards automatically generating summary comments for java methods. In: Proceedings of the IEEE/ACM International Conference on Automated Software Engineering. In: ASE ’10, ACM, New York, NY, USA, pp. 43–52. http: //dx.doi.org/10.1145/1858996.1859006, http://doi.acm.org/10.1145/1858996.1859006.
[11]Moreno, L., Aponte, J., Sridhara, G., Marcus, A., Pollock, L., Vijay-Shanker, K., 2013. Automatic generation of natural language summaries for Java classes. In: Program Comprehension, ICPC 2013 IEEE 21st International Conference on. pp. 23–32. http://dx.doi.org/10.1109/ICPC.2013.6613830.
[12]Iyer, S., Konstas, I., Cheung, A., Zettlemoyer, L., 2016. Summarizing source code using a neural attention model. In: Proceedings of the 54th Annual Meeting of the Association for Computational. pp. 2073–2083. http://dx.doi.org/10.18653/v1/P16-1195.
[13]Allamanis, M., Peng, H., Sutton, C., 2016. A convolutional attention network for extreme summarization of source code. In: Proceedings of the 33rd International Conference on Machine Learning, PMLR, vol. 48. PMLR, pp.2091–2100.
[14]Hu, X., Li, G., Xia, X., Lo, D., Jin, Z., A deep code comment generation, in: Proceedings of the 26th IEEE International Conference on Program Comprehension, 2018, pp. 200–210.
[15]Hu, X., Li, G., Xia, X., Lo, D., Lu, S., Jin, Z., 2018. Summarizing Source Code with Transferred API Knowledge. pp. 2269–2275. http://dx.doi.org/10.24963/ijcai.2018/314.
[16]Mou, L., Li, G., Zhang, L., Wang, T., Jin, Z., 2016. Convolutional neural networks over tree structures for programming language processing. In: Proceedings of the Thirtieth AAAI Conference on Artificial Intelligence. In: AAAI’16, AAAI Press, pp. 1287–1293, http://dl.acm.org/citation.cfm?id=3015812.3016002.
[17]White, M., Tufano, M., Vendome, C., Poshyvanyk, D., 2016. Deep learning code fragments for code clone detection. In: Proceedings of the 31st IEEE/ACM International Conference on Automated Software Engineering. In: ASE 2016, ACM, New York, NY, USA, pp. 87–98. http://dx.doi.org/10.1145/2970276.2970326, http://doi.acm.org/10.1145/2970276.2970326.
[18]Jiang, L., Misherghi, G., Su, Z., Glondu, S., 2007. DECKARD: Scalable and accurate tree-based detection of code clones. In: Proceedings of the 29th International Conference on Software Engineering. In: ICSE ’07, IEEE Computer Society, Washington, DC, USA, pp. 96–105. http://dx.doi.org/10.1109/ICSE.2007.30, http://dx.doi.org/10.1109/ICSE.2007.30.
[19]Gabel, M., Jiang, L., Su, Z., 2008. Scalable detection of semantic clones. In:Proceedings of the 30th International Conference on Software Engineering.In: ICSE ’08, ACM, New York, NY, USA, pp. 321–330. http://dx.doi.org/10.1145/1368088.1368132, http://doi.acm.org/10.1145/1368088.1368132.
[20]Guo, J., Cheng, J., Cleland-Huang, J., 2017. Semantically enhanced software traceability using deep learning techniques. In: 2017 IEEE/ACM 39th International Conference on Software Engineering, ICSE. pp. 3–14. http://dx.doi.org/10.1109/ICSE.2017.9.
[21]Gu, X., Zhang, H., Zhang, D., Kim, S., 2016. Deep API learning. In: Proceedings of the 2016 24th ACM SIGSOFT International Symposium on Foundations of Software Engineering. In: FSE 2016, Association for Computing Machinery, New York, NY, USA, pp. 631–642. http://dx.doi.org/10.1145/2950290.2950334, https://doi.org/10.1145/2950290.2950334.
[22]Xu, B., Ye, D., Xing, Z., Xia, X., Chen, G., Li, S., 2016. Predicting semantically linkable knowledge in developer online forums via convolutional neural network. In: 2016 31st IEEE/ACM International Conference on Automated Software Engineering, ASE. pp. 51–62.
[23]Lin, G., Zhang, J., Luo, W., Pan, L., Xiang, Y., Vel, O.D., Montague, P., 2018. Crossproject transfer representation learning for vulnerable function discovery. IEEE Trans. Ind. Inf. 14 (7), 3289–3297. http://dx.doi.org/10.1109/TII.2018.2821768.
[24]Wang, S., Liu, T., Tan, L., 2016. Automatically learning semantic features for defect prediction. In: Proceedings of the 38th International Conference on Software Engineering. In: ICSE ’16, ACM, New York, NY, USA, pp. 297–308. http://dx.doi.org/10.1145/2884781.2884804, http://doi.acm.org/10.1145/2884781.2884804.
[25]Zhang, J., Wang, X., Zhang, H., Sun, H., Wang, K., Liu, X., 2019. A novel neural source code representation based on abstract syntax tree. In: 2019 IEEE/ACM 41st International Conference on Software Engineering, ICSE. IEEE,pp. 783–794.