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

赵衔麟 等: 面向代码注释生成任务的注释质量评价研究 3755

29.7% 26.8% 33.8%
20 000
400 000
17 500 80 000 22.6%
23.3%
15 000 60 000 20.1% 300 000 23.0% 24.2%
Number 12 500 15.7% 13.7% Number 40 000 13.9% Number 200 000
10 000
7 500
7.7% 7.6% 10.2%
5 000 20 000 100 000
2 500
0 0 0
12 18 24 30 36 42 48 54 60 12 18 24 30 36 42 48 54 60 12 18 24 30 36 42 48 54 60
0 6 0 6 0 6
comment_len comment_len comment_len
TLC CSN Funcom
图 3 3 个数据集 comment_len 指标分布

图 4 展示了一些具体的与注释简洁性有关的案例. 例 1 的注释过长 (高达 236) 而代码本身的内容较为简单.
这样的注释不够简洁. 而例 2 和例 3 的注释都过于简短, 分别只有一个词和两个词. 此外, 例 2 只是重复了方法名;
例 3 只是重复了返回值的类型. 这些信息都可以从代码中直接读出, 没有必要在注释中重复. 因此这样的注释过于
简短以致没有提供有效信息. 由此可见, 过长或过短的注释都可能存在质量问题. 例 4 的注释 conciseness 值非常
高, 在代码长度仅为 7 的情况下, 注释显得格外冗长, 其将能从代码中直接获得的信息描述得过于详细. 例 5 的注
释 conciseness 值则过低, 代码长度为 636, 较为复杂, 而注释几乎只重复了方法名. 由此可见, conciseness 指标过高
或过低都可能意味着注释质量较差.

例1 注释：description - - - - - - - - - - - landr ( ) is the las2 driver routine that ,
upon entry, ( 1 ) checks for the validity of input parameters of the b - eigenproblem comment_len: 236
( 2 ) determines several machine constants ( 3 ) makes a lanczos run ( 4 ) calculates code_len: 26
b-eigenvectors ( singular vectors of a ) if requested by user arguments (…内容省略) conciseness: 9.076 9
static void fake_memset_127(double[] a) {…}
comment_len: 1
例2 注释：buildcombomap code_len: 26
private void buildComboMap() {…}
conciseness: 0.038 5
例3 注释：returns filepreference comment_len: 2
public FilePreference getNewFilePreference() {…} code_len: 67
conciseness: 0.029 9
例4 注释：public method to validate system name for configuration returns 'true' if system
name has a valid meaning in current configuration , else returns 'false' for now , this comment_len: 38
method always returns 'true' ; it is needed for the abstract light class code_len: 7
public boolean validSystemNameConfig(String systemName) { return ( _BOOL ) ; } conciseness: 5.428 6
例5 注释：tar a file comment_len: 3
protected void tarFile(ArchiveEntry entry, TarArchiveOutputStream tOut, String vPath) code_len: 636
throws ArchiverException, IOException{ conciseness: 0.004 7
// 代码过长, 省略…
}
图 4 代码注释简洁性分析的若干案例

4.3 自然性
本文通过 flesch_ease 和 grammar_error 两个指标度量代码注释的自然性, flesch_ease 的值越高代表注释的阅
读难度越低, grammar_error 的值越高代表注释可能的语法错误越多. 表 8 展示了 3 个开放数据集在这两个指标上
的均值与中位数. 可以发现: 在 flesch_ease 指标上, CSN 数据集略低于 TLC 和 Funcom 数据集, 说明其注释的阅读
难度略大; 在 grammar_error 指标上, Funcom 数据集的值明显低于另外二者, 说明其注释的语法错误较少.

表 8 3 个数据集在自然性指标上的均值和中位数

flesch_ease grammar_error
数据集
均值 中位数 均值 中位数
TLC 63.224 5 65.73 0.163 6 0
CSN 60.148 9 63.36 0.152 4 0
Funcom 62.759 8 66.40 0.020 5 0