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

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

含对主流的代码注释语料库的分析, 以及对代码注释质量的人工评估方法和自动评估方法的总结, 对前者的介绍
较为简单, 对后者同样只介绍了 BLEU 等 4 个基于相似性的指标. Rani 等人 [34] 则是对“如何评价注释的总体质量”进
行综述, 所收集的文献不仅与代码注释相关, 而且涵盖了软件文档 (如需求文档、API 文档) 的质量评价, 由此得
到 21 种质量属性, 但其中多个属性不适用于代码注释生成任务的评价. 上述工作均没有使用量化的注释质量评价
方法对现有注释生成任务中的数据集以及生成注释的质量进行分析. 本文与这些工作的区别在于: 总结了一套量
化的注释质量评价指标, 并首次利用这套指标对当前注释生成任务的主流数据集以及自动生成的注释的质量进行
了评价和分析, 给出了一些具有参考价值的研究发现, 有助于揭示当前注释生成任务面临的问题, 推动注释生成技
术的发展和注释质量评价的研究.
综上, 对比现有工作, 本文的主要贡献如下.
(1) 总结并设计了一套量化的代码注释质量评价指标, 并首次将这套指标应用于代码注释生成任务中人工注
释和生成注释的质量评价, 增强了注释质量评价的有效性.
(2) 基于上述指标对当前主流开放数据集中的代码注释进行了质量评价和分析, 揭示了当前开放数据集中的
代码注释质量存在的典型问题, 提出未来研究需要关注高质量代码注释数据集的构建.
(3) 基于上述指标对典型注释生成方法 CodeT5 生成的注释进行了质量评价和分析, 揭示了当前自动生成注释
的特点以及不足, 提出未来注释生成方法需要帮助开发者生成表达代码高层意图或传递额外信息的注释.
(4) 针对近期研究反映的大语言模型 ChatGPT 生成的注释 BLEU 值低的现象, 基于上述评价指标对其生成的
注释进行了质量评价和分析, 指出未来更应该根据开发者意图和具体场景进行具有针对性的注释质量评价.
本文第 1 节介绍代码注释质量评价问题的定义和本文的研究问题. 第 2 节介绍本文的研究方法. 第 3 节总结
归纳现有的注释质量评价维度和评价方法, 并介绍本文使用的评价指标. 第 4 节对开放数据集进行质量评价和分
析. 第 5 节对典型方法 CodeT5 生成的代码注释进行质量评价和分析, 指出当前注释生成工作面临的问题. 第 6 节
对 ChatGPT 生成的注释质量进行分析. 第 7 节进行本文工作的有效性分析. 第 8 节总结全文并对代码注释生成与
质量评价的未来研究给出建议.

1 问题定义与研究目标

1.1 问题定义
如何评价代码注释的质量是一个宽泛的问题, 目前关于什么是“好注释”“坏注释”, 学术界和产业界并没有达
成明确的共识. 按照国家标准 GB/T19000: 2016 [35] , 质量是指客体的一组固有特性满足要求的程度. 其中, “特性”指
可区分的特征. 不同客体可以有各种类的特性, 如物体的机械性能, 感官的气味、噪音、色彩等; “要求”则是指明
示的、通常隐含的或必须履行的需求或期望. 因此, 本文定义一条代码注释的质量是指该注释满足规定需要和潜
在需要的特征的程度. 其涉及 3 个方面的要素.
(1) 代码的情况: 注释是为代码而写的, 因此在评价注释质量时不可忽略代码的情况. 注释的内容必须和代码
相关, 并对代码进行针对性的说明和解释. 目前注释生成任务采取的相似性指标均没有考虑到代码的情况.
(2) 注释的情况: 注释质量评价的直接对象就是注释的内容, 其评价的结果与注释的内容直接相关. 目前注释
生成工作采取的相似性指标反映的是生成注释和人工参考注释的相似性, 缺少对注释本身内容的直接评价.
(3) 评价的维度: 注释本身在内容或风格上有多方面的特征, 如准确性、完整性等. 在实际应用中, 开发者根据
自身的需求会对注释有多方面的期望, 因此评价注释的质量时需要选择多个维度.
综上, 代码注释质量评价可定义为: 基于一条注释 m 帮助开发者阅读和理解代码 c 的具体需要, 定义评价维
度 W, 基于 W 给出 c 的定性或定量的质量评价结果 Q W . 即:
(1)
f(c,m|W) → Q W
需要特别指出的是, 代码注释质量的评价与代码注释生成方法的评价之间既有区别又有关联. 其区别体现在:
代码注释的质量评价是指一条注释满足开发者阅读和理解代码的需要的程度, 而代码注释生成方法的评价关注的