一种面向对象程序的注释质量评价和注释建议方法
【专利摘要】本发明公开了软件工程领域内的一种面向对象程序的注释质量评价和注释建议方法，包括以下步骤：1）遍历目标代码文件，提取代码文件中主类的注释和其所注释的类名、方法的注释和其所注释的方法名，步骤2-1）：根据关于主类注释的分析规则对主类文件中的注释部分与类名进行质量分析，并对不满足分析规则的注释给出相应的建议；步骤2-2）：根据关于方法注释的分析规则对方法文件中的注释部分与方法名进行质量分析，并对不满足分析规则的注释给出相应的建议；步骤3）：根据上述的建议的数量来给出整体的质量评价，本发明根据所计算的结果给出关于头注释和方法注释的建议，提高代码注释的质量，有利于对软件代码质量的完善，可用于软件的维护开发中。
【专利说明】一种面向对象程序的注释质量评价和注释建议方法
【技术领域】
[0001] 本发明涉及一种软件评价方法，特别涉及一种软件注释质量评价及建议方法，属 于软件工程领域。
【背景技术】
[0002] 在一个代码文件中，不仅仅有代码，而且还有注释。现在有研究表明，有注释的代 码比没有注释的代码更容易理解。且注释是仅次于代码本身的有利于代码理解的第二有 用文档。此外，源代码文件在软件维护是重要的，对于整个代码文件来说，查看在源代码文 件中的注释对于开发人员对文档和代码的更新是一个比较方便的方法。而且开发人员都认 为一个代码文件的质量严重影响了开发人员对这个软件的维护和演化，所以他们都认为代 码文件质量很重要。而一个代码文件的质量不仅仅包括代码的质量，而且还包括代码中注 释的质量，同时注释的质量不仅仅包括已有注释的质量，对没有注释却需要注释的也会影 响代码文件的质量。对注释质量的评价在软件开发过程和维护过程中都有其作用。在开发 过程中，管理人员可通过注释质量去评判各开发人员的代码质量和可理解性，注释质量好 的代码能够有效辅助代码的可测试性和可维护性；在软件维护过程中，维护人员可通过注 释质量来判断当前程序的易修改性，注释质量好的代码能够有效的帮助维护人员来修改维 护这个程序。所以本发明通过对于已有注释和对没有注释却需要注释的两个方面分析来整 体的分析这个代码文件注释的质量。
[0003] 已有的注释质量的分析往往都是对已有注释的分析，忽略了对没有注释却需要注 释的分析，而且对于有注释，都是计算注释在这代码文件的比例，或者是代码注释的单词个 数等等，而本发明是运用信息检索，对代码文件注释与被注释的代码的提取，通过预处理， 然后计算其之间的相关性。对于没有注释的，提取每个代码文件的方法名，并在预处理的 同时计算其方法的代码行数和调用其他函数的次数，通过分析3个条件来判断是否需要注 释。本发明充分利用信息检索技术，通过检索代码和注释部分来计算其相关性，和其是否需 要注释，来给出关于注释质量的评价，并给出注释的建议。
【发明内容】
[0004] 本发明的目的是提供一种面向对象程序的注释质量评价和注释建议方法，根据所 计算的结果给出关于头注释和方法注释的建议，提高代码注释的质量，有利于对软件代码 质量的完善。
[0005] 本发明的目的是这样实现的：一种面向对象程序的注释质量评价和注释建议方 法，包括以下步骤： 步骤1)遍历目标代码文件，提取代码文件中主类的注释和其所注释的类名、方法的注 释和其所注释的方法名，将主类的注释和其所注释的类名存入主类文件内，将方法的注释 和其所注释的方法名存入方法文件内； 步骤2-1):根据关于主类注释的分析规则对主类文件中的注释部分与类名进行质量分 析，并对不满足分析规则的注释给出相应的建议； 步骤2-2):根据关于方法注释的分析规则对方法文件中的注释部分与方法名进行质量 分析，并对不满足分析规则的注释给出相应的建议； 步骤3):根据上述的建议的数量来给出整体的质量评价。
[0006] 作为本发明的进一步限定，所述步骤2-1)的质量分析方法如下： a) 遍历主类文件中的注释部分，检索该注释部分是否存在"author"，如果不存在，则 给出添加作者的建议； b) 查看该注释部分是否存在对主类的描述，如果不存在，则给出添加描述的建议，如果 存在对主类的描述，则分析其相关性； c) 分析相关性，利用公式L=N/M*100%计算出注释与主类的相关性，其中Μ表示对类名 进行骆驼式命名法后分割出的单词总数，Ν表示注释中与类名相关的单词的个数，并将L与 预先设定的门槛值比较，如果大于门槛值，说明相关性较高，如果低于门槛值，说明相关性 较低，并且给出添加更多描述的建议。
[0007] 作为本发明的进一步限定，所述步骤2-2)的质量分析方法如下： a) 遍历方法文件中的注释部分和方法名，统计有注释的方法名和没有注释的方法名， 并利用公式X=Y/Z*100%计算有注释的方法名，Y表示有注释的方法的个数，Z表示方法文件 中方法的总数，并将X与预先设定的门槛值比较，如果低于门槛值，给出添加更多注释的建 议； b) 对方法文件中有注释的方法名进行相关性分析，根据骆驼式命名法来分割出方法名 中的单词，单词数记Q，再依次对分割出的单词来遍历文件中的注释，注释中含有的单词数 记P，利用公式〇=P/Q*l〇〇%，将〇与预先设定的门槛值进行比较，如果低于所设门槛值，则给 出添加更多注释的建议，如果高于所设门槛值，说明该段注释描述与该代码文件中的主类 相关性较高； c) 对方法文件中没有注释的方法名进行分析，利用wordnet工具分析方法名的词性组 成； 如果该方法名的词性的组成不是动词加名词或者不是名称加动词的话，说明该方法需 要添加注释，给出添加注释的建议； 如果是动词加名词或者是名称加动词则分析其代码行数，如果其代码行数大于所设门 槛值，则需要添加一些注释来有利于代码的理解，给出添加注释的建议； 如果代码行数小于门槛值，则分析其引用其他方法的次数，如果次数大于门槛值，则需 要添加一些注释来有利于代码的理解，给出添加注释的建议，如果词数小于门槛值，则可以 不加注释。
[0008] 作为本发明的进一步限定，所述步骤3)的质量评价方法如下：通过统计上述质量 分析所给出的建议，然后计算出建议率，利用公式
【权利要求】
1. 一种面向对象程序的注释质量评价和注释建议方法，其特征在于，包括以下步骤： 步骤1)遍历目标代码文件，提取代码文件中主类的注释和其所注释的类名、方法的注 释和其所注释的方法名，将主类的注释和其所注释的类名存入主类文件内，将方法的注释 和其所注释的方法名存入方法文件内； 步骤2-1):根据关于主类注释的分析规则对主类文件中的注释部分与类名进行质量分 析，并对不满足分析规则的注释给出相应的建议； 步骤2-2):根据关于方法注释的分析规则对方法文件中的注释部分与方法名进行质量 分析，并对不满足分析规则的注释给出相应的建议； 步骤3):根据上述的建议的数量来给出整体的质量评价。
2. 根据权利要求1所述的一种面向对象程序的注释质量评价和注释建议方法，所述步 骤2-1)的质量分析方法如下： a) 遍历主类文件中的注释部分，检索该注释部分是否存在"作者"，如果不存在，则给出 添加作者的建议； b) 查看该注释部分是否存在对主类的描述，如果不存在，则给出添加描述的建议，如果 存在对主类的描述，则分析其相关性； c) 分析相关性，利用公式L=N/M*100%计算出注释与主类的相关性，其中Μ表示对类名 进行骆驼式命名法后分割出的单词总数，Ν表示注释中与类名相关的单词的个数，并将L与 预先设定的门槛值比较，如果大于门槛值，说明相关性较高，如果低于门槛值，说明相关性 较低，并且给出添加更多描述的建议。
3. 根据权利要求1所述的一种面向对象程序的注释质量评价和注释建议方法，所述步 骤2-2)的质量分析方法如下： a) 遍历方法文件中的注释部分和方法名，统计有注释的方法名和没有注释的方法名， 并利用公式X=Y/Z*100%计算有注释的方法名，Y表示有注释的方法的个数，Z表示方法文件 中方法的总数，并将X与预先设定的门槛值比较，如果低于门槛值，给出添加更多注释的建 议； b) 对方法文件中有注释的方法名进行相关性分析，根据骆驼式命名法来分割出方法名 中的单词，单词数记Q，再依次对分割出的单词来遍历文件中的注释，注释中含有的单词数 记P，利用公式〇=P/Q*l〇〇%，将〇与预先设定的门槛值进行比较，如果低于所设门槛值，则给 出添加更多注释的建议，如果高于所设门槛值，说明该段注释描述与该代码文件中的主类 相关性较高； c) 对方法文件中没有注释的方法名进行分析，利用wordnet工具分析方法名的词性组 成； 如果该方法名的词性的组成不是动词加名词或者不是名称加动词的话，说明该方法需 要添加注释，给出添加注释的建议； 如果是动词加名词或者是名称加动词则分析其代码行数，如果其代码行数大于所设门 槛值，则需要添加一些注释来有利于代码的理解，给出添加注释的建议； 如果代码行数小于门槛值，则分析该方法引用其他方法的次数，如果次数大于门槛值， 则需要添加一些注释来有利于代码的理解，给出添加注释的建议，如果词数小于门槛值，则 可以不加注释。
4.根据权利要求1所述的一种面向对象程序的注释质量评价和注释建议方法，所述步 骤3)的质量评价方法如下：通过统计上述质量分析所给出的建议，然后计算出建议率，利 用公式
其中，Suggestion-rate表示建议率,
表示对主类注释建议的总 数，括号内的3表示对主类的注释分析一共有三种，
表示对有注释的方法 建议总数，
表示有注释的方法总数，
表示没有注释的方法的建 议总数，
表示没有注释的方法总数，
表示对主类注释建议占的比 重，
表示对有注释的方法建议占的比重，
表示对没有注释的方法 建议占得比重，将建议率与预先设定的门槛值进行比较，如果大于门槛值，说明该代 码文件注释的质量不好，需要好好改进，建议开发人员根据建议修改注释，建议率小 于0.5,说明该代码文件的质量较高；如果所有方法具有注释，s卩
，则
【文档编号】G06F17/27GK104123273SQ201410355299
【公开日】2014年10月29日 申请日期:2014年7月24日 优先权日:2014年7月24日
【发明者】孙小兵, 耿强, 李云, 朱俊武 申请人:扬州大学