Page 327 - 《软件学报》2025年第8期
P. 327

3750                                                       软件学报  2025  年第  36  卷第  8  期


                 汇相似度, 能够间接反映注释的准确性/相关性. 上述第               1  种途径, 即注释与代码的不一致检测, 更适合看作单独的
                 任务开展研究, 难以抽象出具体的评价指标. 为此, 本文主要关注第                   2  种注释评价途径.
                    关于第   2  种途径, Corazza 等人  [81,82] 研究了注释与代码的一致性和注释与代码的词汇相似度的关系. 他们对                 3
                 个  Java 软件系统的方法与注释的一致性进行人工标注, 并计算相应的词汇相似度. 结果显示, 当注释与方法的实
                 现一致时, 词汇相似度会更高. McBurney        等人  [83] 使用  3  个短文本语义相似度指标     (short text semantic similarity
                 metrics) 分析了代码和注释的文本相似度, 同样发现注释的准确性可以部分通过文本相似度估计. 此外, Iammarino
                 等人  [84] 发现, 代码与注释在主题分布上的相似性能够反映一致程度. 他们将代码与注释分别处理, 应用                         LDA  模型
                 分别抽取主题, 最终计算二者的          KL  散度以判断代码与注释的一致性. Rabbi 等人         [85] 也利用了主题建模方法判断代
                 码与注释的一致性.

                 3.1.2    完整性
                    完整性是指注释不能缺失重要的信息或只包含少数事实从而影响开发者对代码的理解. 完整性的定义需要视
                 具体的场景而定, 不同的场景下所需要的注释内容是不同的. Khamis 等人                   [86] 提出的  JavadocMiner 检查  Javadoc 注
                 释是否记录了方法的返回值、所有的参数以及可能抛出的异常, 相应的内容是否使用了@return, @parameter,
                 @throws 等标签进行注释. Sun    等人  [87] 检查了类注释的完整性, 特别是类注释是否涵盖作者的身份信息: @author
                 标签.

                 3.1.3    简洁性
                    简洁性是指注释应当简洁, 避免包含不必要或不相关的内容. Khamis 等人                    [86] 提出的  JavadocMiner 方法计算
                 类注释的平均词数, 以评价某个类的注释是否简洁. Steidl 等人               [21] 提出的注释质量模型使用注释长度判断行注释
                 的简洁性. 注释过短      (例如仅有   2  个单词) 意味着该注释过于简洁, 质量较低; 注释过长             (例如至少有    30  个单词) 意
                 味着注释不够简洁, 可能包含无法从代码中获得的信息, 不应都写在代码行之间.

                 3.1.4    自然性/流畅性
                    自然性/流畅性评价的是注释是否语法正确, 文字流畅, 易于开发者理解. Khamis 等人                     [86] 使用一系列启发式规
                 则评价注释的自然性, 包括计算注释中的词元、名词、动词以及缩略词的数量. 他们指出注释应当避免出现缩略
                 词, 否则会对开发者的理解造成影响. 他们还计算了               Flesch-Kincaid grade level score, Flesch reading ease level 等自
                 然语言理解领域的可读性指标, 以评价注释的可读性. Scalabrino             等人  [88,89] 也计算了  Flesch-Kincaid  指标, 以评价注
                 释的可读性.

                 3.1.5    有用性/信息量
                    注释是在代码之外提供额外信息的, 因此注释的有用性与其蕴含的信息量密切相关. 有用性/信息量这一维度
                 评价的是注释是否包含足量的可以帮助开发者理解代码的信息. 特别是随着代码命名规范的普及, 许多代码呈现
                 出自描述性, 代码本身就已经传达丰富的信息, 如果注释仅仅重复了代码, 那就没有提供额外的信息, 其有用性就
                 会受到局限.
                    Steidl 等人  [21] 提出了一个涉及注释信息量的质量模型. 他们针对方法级注释定义了一致性系数                      c_coeff 指标,
                 用于刻画注释中与方法名切分后的某个词汇相似                  (词语之间的编辑距离小于         2) 的词所占的比例. 他们认为如果
                 c_coeff 过高  (例如大于  0.5), 则该注释缺少不能从代码中明显获知的额外信息. Sun             等人  [87] 后续对  c_coeff 的计算
                 进行了改进. Aman   等人  [90] 使用  Doc2Vec 方法, 将包含注释的代码与去除注释的代码分别表示为向量, 计算二者的
                 相似度. 其认为如果注释提供了更多丰富的信息, 那么两个向量的差异会更大.

                 3.1.6    其他评价维度
                    除了上述维度外, 研究者们还在更宏观的维度探讨了注释的质量评价问题. 例如注释的存在性                              [2] 、必要性  [91] 、
                 有效性  [9] 、注释的语言问题    [92]  , 链接问题  [93] 等, 这些维度较为宏观且难以实际量化, 这里不一一展开.

                 3.2   本文选取的评价维度与指标
                    本文目标是选取一套量化的注释质量评价指标对开放数据集和自动生成的注释质量进行评价和分析. 从第
   322   323   324   325   326   327   328   329   330   331   332