Page 329 - 《软件学报》2025年第8期

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

(2) conciseness
由于注释与代码密切相关, 如果代码非常长, 则逻辑较为复杂, 可能需要更多的注释内容. 因此本文基于上述
指标设计了注释的相对长度指标 conciseness. 记代码的长度为 code_len, 相对长度指标为:

comment_len
conciseness = (8)
code_len

3.2.3 自然性评价指标
(1) flesch_ease
首先, 本文参考 Khamis 等人 [86] 和 Scalabrino 等人 [88] 的工作, 使用可读性分数 Flesch reading ease level 来评价
注释的自然性, 其旨在反映阅读和理解文本的难易程度 [96] , 简称为 flesch_ease, 具体计算如下:
记注释的单词数为 words, 总字符数为 characters, 总音节数为 syllables, 句子数为 sentences. 则 flesch_ease 指
标计算如下, 其值越高代表文本越容易阅读.

words syllables
flesch_ease = 206.835−1.015× −84.6× (9)
sentences words
(2) grammar_error
在实际应用中, 代码注释除了需要容易阅读, 还需要在一定程度上保障语法正确, 但已往工作均没有涉及. 本
文设计了一个与语法相关的指标 grammar_error, 将注释输入开源语法检查工具 nlprule (https://github.com/
bminixhofer/nlprule), 检查工具产生的语法建议的数量. 如果注释违反了该工具内置的 800 余条语法规则, 工具就
会产生语法建议. 记一条代码注释产生的语法建议的数目为 num, 则:

grammar_error = num (10)

3.2.4 有用性评价指标
代码注释的一个重要目标是为了辅助开发者阅读和理解代码. 为此, 代码注释的有用性, 即评价注释是否包含
可以帮助开发者理解代码的信息, 是代码注释质量评价的重要指标. 研究表明 [97] , 开发者通常期望代码注释并不
是代码中方法签名的简单重复, 而应该提供代码之外的补充信息 [20] , 以帮助更好地理解代码. 为了评价注释的有
用性/信息量, 本文定义了如下两个指标.
(1) coefficient
该指标在 Stedil 等人 [21] 和 Sun 等人 [87] 提出的 c_coeff 指标上进行了调整. 记注释的词数为 len, 方法签名和注
释切词和词根化处理后共同出现的词数为 bothNum, 则 coefficient 的计算公式如下:

bothNum
coefficient = (11)
len
本文没有通过编辑距离来判断两个词语是否相同, 而是统一进行词根化处理, 以消除词语时态、单复数等因
素的影响. 该指标主要刻画的是注释中方法签名已经可以体现出的内容所占的比例. 如果该指标过高, 表明注释可
能仅仅是重复了代码, 没有提供额外的信息.
(2) mesia
上述指标 coefficient 仅考虑了注释中与方法签名重复的词汇的占比, 而注释中除了方法签名之外额外提供的
信息的多少是反映注释有用性的重要方面. 为了评价注释相对于方法签名的信息补充程度, 本文作者借鉴香农的
信息熵理论 [98] , 在前期工作中提出了 mesia 指标 [94] . 其计算方法如下所示.
定义语料库中的一条注释为 C = < w 1 ,w 2 ,...,w n >, 注释集合为 Comments = {C 1 ,C 2 ,...,C m }, 语料库的词汇集合
m ∪
为 W = {w|w ∈ C i }. 记每个词 w 在 W 中出现的频率为 p(w|W), 则对于一条注释 C, 其方法签名的词汇集合 Code,
i=1
有:

∑
− log(p(w|W))
mesia = w∈C∧w<Code (12)
len(C)
mesia 指标刻画了注释中不在方法签名内的词汇所带来信息的程度, 其中信息量的计算是通过单词在语料库