代码注释可视化工具：Annotation Visualizer

软件影响16（2023）100491原始软件出版物Annotation Visualizer：用于代码注释的软件可视化工具PhyllipeLimaa，Nathalya StefhanyPereirab，EveraldoGomesc，EduardoGuerrad，Paulo Meirellesca巴西，伊塔朱巴联邦大学-IMC-贝伊b巴西国家电信研究所c圣保罗大学-IME-USP，巴西d意大利博尔扎诺-博尔岑-UniBZ自由大学A R T I C L E I N F O保留字：代码注释圆包装Web应用程序软件可视化开源工具A B标准注释可视化工具（Annotation Visualizer，AVisualizer）是一个软件可视化工具，用于显示给定目标基于Java的软件系统中的代码注释分布。作为一个Web应用程序实现，它可以从目标源代码中提取注释使用情况，并使用分层循环打包方法显示它。使用一套专用的软件度量，它可以显示与大小相关的信息和与注释使用相关的代码职责。该工具提供了所分析系统的三种不同视图，每种视图具有不同的粒度。AVisualizer是一个帮助提高代码理解能力的工具代码元数据当前代码版本v1.0.0用于此代码版本的代码/存储库的永久链接https://github.com/SoftwareImpacts/SIMPAC-2023-73可再生胶囊的永久链接https://codeocean.com/capsule/6899091/tree/v1GNU Affero通用公共许可证第3版（AGPL-3.0）使用git的代码版本控制系统使用TypeScript的软件代码语言、工具和服务 JavaScript， 爪哇， JDK 11编译要求、操作环境依赖性JRE 11或更高版本、Node v16.10.0、Yarn v1.22.17、Maven如果可用开发人员文档/手册链接https://github.com/metaisbeta/avisualizer#readme问题支持电子邮件phyllipe@unifei.edu.br1. 介绍代码注释是Java编程语言的一项功能，它可以直接在编程元素（如方法和类）上配置自定义元数据。由于注释是直接插入到源代码中的，因此它们是配置Meta数据的一种方便快捷的替代方法。我们的研究在Java开源项目中进行[1]，在78%的类中至少有一个代码注释，加强了它们的流行性。此外，我们的同伴工作[2]证明了代码责任和代码注释之间存在关系原文DOI：https://doi.org/10.1016/j.infsof.2022.107089。在这种情况下，注释可视化器（AVisualizer）是一种实现CADV（代码注释分布可视化）的工具，这是一种在我们的同伴工作中定义和验证的代码注释的软件可视化方法[2]。CADV使用一种圆形包装方法来显示分析中的Java系统中的代码注释使用和分布，以及包和类的底层层次结构。它还使用颜色来区分注释的包，并根据分析系统的结构对代码注释进行本文中的代码（和数据）已由Code Ocean认证为可复制：（https://codeocean.com/）。更多关于生殖器的信息徽章倡议可在https://www.elsevier.com/physical-sciences-and-engineering/computer-science/journals上查阅。∗通讯作者。电子邮件地址：phyllipe@unifei.edu.br（P. Lima），nathalya. gec.inatel.br（N.S.Pereira），everaldogjr@gmail.com（E.Gomes），eduardo. unibz.it（E.Guerra），paulormm@ime.usp.br（P. Meirelles）。https://doi.org/10.1016/j.simpa.2023.100491接收日期：2023年2月14日;接受日期：2023年3月6日2665-9638/©2023由Elsevier B. V.发布。这是CC BY-NC-ND许可证下的开放获取文章（http://creativecommons.org/licenses/by-nc-nd/4.0/）。可在ScienceDirect上获得目录列表软件影响杂志 首页：www.journals.elsevier.com/software-impactsP. Lima，N.S. 佩雷拉E. Gomes等人软件影响16（2023）1004912Fig. 1. AVisualizer基本构建块。图二. 使用org.junit注释模式的示例。Hasselbring等人的工作[3]评论说，开发人员在添加和维护功能之前花费了大部分时间来理解软件。为了克服这一点，CADV的主要目标之一是是通过软件可视化来帮助理解软件。我们将AVisualizer实现为Web应用程序。我们还扩展并开发了一个与IntelliJ IDE集成的插件[4]，Java开发环境。尽管代码注释是一个流行的功能，我们找不到任何软件可视化方法或工具专注于他们。开发AVisualizer是为了在我们的同伴工作中实现和验证CADV方法[2]。针对此方法进行的所有实证评估均使用AVisualizer Web应用程序。2. 软件描述AVisualizer是一个Web应用程序，分为两个主要组成部分：（i）后端负责从目标项目中提取注释度量值;（ii）前端负责使用这些度量值渲染圆 包装（CADV方法 ）。为 了渲染 圆形包 装，我 们使用 了D3.jsJavaScript库[5]。图1显示了AVisualizer的基本构建块。后端被包装为SpringBoot应用程序，前端是React应用程序。我们配置了一个maven构建，以生成一个带有应用程序的可执行jar文件。有关构建过程的信息可以在公共存储库中获得12.1. 代码注释度量提取后端主要由一个名为Annotation Sniffer（ASniffer）的Java工具组成[6]，如图1的左半部分所示。本课题组第1https://github.com/metaisbeta/avisualizer开发了ASniffer来从Java源代码中收集代码注释指标。这是一套7个度量标准，提取代码注释大小、复杂性、耦合和注释模式。它们在我们以前的 工 作 中 被 定 义 和 验 证 [1] 。 ASniffer 是 一 个 独 立 的 组 件 ， 用 作AVisualizer后端的依赖项代码注释的注释模式是一个重要的概念，因为它极大地影响了AVisualizer工具的前端。基于注释的API或基于元数据的框架定义并公开一组注释，以便应用程序开发人员可以使用它们来配置编程元素并执行所需的行为。这组符号定义API的给定域的元数据结构 定义为注释模式[1]。图中的代码2、介绍Java负责使用JUnit 4框架执行单元测试的类。注释@Test、@After、@Before属于软件包org.junit。在本例中，我们将这个注释集作为org.junit注释模式的一部分。实际上，提取注释模式的自动化方法是识别导入的用于注释的包。另一个流行注释模式的例子是javax.persistence。2.2. CADV渲染在后端提取度量值后，该工具生成一个适合于前端模块的JSON报告，如图1的右侧部分。它使用React库和D3.Js开发，读取此JSON报告并构建CADV可视化。CADV包括三个不同的软件可视化视图，每个视图以不同的粒度和范围显示分析中的软件。（i）系统视图显示完整的系统和由包分发的注释。（ii）Package View显示单个包（和嵌套包），其注释分布在所显示包的类（三）类视图P. Lima，N.S. 佩雷拉E. Gomes等人软件影响16（2023）1004913图三. AVisualizer应用程序呈现地理存储区项目。显示单个类以及该类内代码元素中批注的分布。视图使用颜色来区分注释的类型和分组，即， 注释模式。 这些圆的大小遵循所选的代码注释度量值。 我们的配套文件[2]包含CADV方法的细节和设计，以及进行的评估当执行时，AVisualizer向用户展示一个正在分析的示例项目，如图所示。3 .第三章。默认值为G eostore2项目。导航栏有一个演示选项，用户可以显示另外两个项目。AVisualizer有三个主要区域向用户传达信息：（i）标题，（ii）视图，（iii）注释模式表。标题包含的信息可指导用户了解正在查看的内容以及当前正在检查项目的哪个部分。它通知正在显示什么包/类，正在使用什么注释度量来确定圆大小，以及当前正在渲染CADV的三个视图中的哪一个，即，系统、包或类视图。 视图是显示实际可视化的区域，位于标题下方。系统视图是打开的可视化视图作为默认值。每个虚线圆圈表示源代码中的一个包，每个彩色圆圈表示特定注释模式中的一个注释或一组注释。每个注释模式都被分配了一种颜色。用户可以单击包（虚线圆圈）或注释（彩色圆圈）进行放大. 在缩放过程中，可视化将更改为包视图或类视图，这取决于用户当前浏览的范围。如上所述，每个视图具有不同的特征，这些特征在可视化过程中相互补充以实现完整性的AVisualizer工具允许在所有三个视图之间导航。注释模式表是一个包含在分析项目中找到的注释模式的表。它显示每个注释模式的颜色以及项目中该注释模式的注释总数。该工具允许用户仅选择他们希望可视化的注释模式用户可以通过单击“选择您的项目”并告知项目在本地计算机上驻留的路径来可视化自己的项目它目前需要一个Java项目作为输入，并不强制要求具有maven或gradle构建文件2https://github.com/geosolutions-it/geostore3. 影响正如我们以前的工作[1，6]，同伴工作[2]以及与文献[7，8]中的其他功能一样，代码注释是一个受欢迎的功能，积极维护，并有助于理解角色或责任 一个类或包。此外，Kotlin、C#和TypeScript等语言也具有类似的功能，这进一步证明了这不仅是Java开发人员的流行编程风格然而，如前所述，我们无法找到一种工具或软件可视化方法，其目标是理解如何在项目中使用代码注释。文学中的形象化聚焦于显示大小，复杂性和内聚性，类型（类，接口，枚举）代表主要元素。根据我们的实证研究结果[2]，我们使用颜色来识别和区分注释模式的方法允许开发人员识别代码责任和架构角色，而不仅仅是大小或复杂性。AVisualizer工具对于我们的配套工作是必不可少的，它有助于评估可视化代码注释的好处。使用AVisualizer，我们可以评估可视化注释有助于开发人员进一步提高他们的系统知识，这有助于维护和进化。简而言之，AVisualizer帮助我们实现了通过软件可视化提高软件理解力的主要目标，专注于其他工具忽略的重要语言特性。4. 局限性和今后的改进AVisualizer专注于显示代码注释，因此它适用于使用基于注释的API的Java系统。 尽管它们很流行，但有些Java项目并不使用它们。在这种情况下，AVisualizer不会对理解过程做出贡献。另一方面，Web应用程序是可以从我们的工具中受益的应用程序的一个例子，因为它们广泛使用基于注释的框架和API，如Spring，JPA，CDI等。第一个与类视图的呈现有关，它提供了类的一些低级细节。这种限制来自CADV方法，而不是工具本身。 但是，该工具可以通过允许用户在此视图中选择他们想要的信息来最大限度地减少此类限制。简而言之，该工具应提供P. Lima，N.S. 佩雷拉E. Gomes等人软件影响16（2023）1004914更多定制。另一个限制是无法直接从可视化导航到源代码。我们将从可用于IntelliJ IDE的AVisualizer的插件版本中解决这个问题。5. 由工具AVisualizer• CADV：一种用于代码注释分发的软件可视化方法。信息和软件技术。2023.DOI：https://doi.org/10.1016/j.infsof.2022.107089CRediT作者贡献声明Phyllipe Lima：概念化，方法论，软件，验证，调查，写作Nathalya Stefhany Pereira ： 软 件 。 Everaldo Gomes ： 软 件 。Eduardo Guerra：概念化，写作保罗·梅雷莱斯：概念化，方法论，写作致谢我们要感谢巴西资助机构 FAPESP（圣保罗研究基金会）赠款2019/12743-4提供的支持。竞合利益作者声明，他们没有已知的竞争性财务利益或个人关系，可能会影响本文报告的工作附录A. 补充数据与本文相关的补充材料可以在网上找到在https://doi.org/10.1016/j.simpa.2023.100491。引用[1]P. Lima，E. Guerra，P. Meirelles，L. Kanashiro，H. 席尔瓦湾，澳-地 Silveira，一 个 用 于 代 码 注 释 评 估 的 工 具 包 套 件 ， J.Syst. Softw. 137 （ 2018 ）163http://www.sciencedirect.com/http://dx.doi.org/10.1016/j.jss.2017.11.024[2]P. Lima，J.Melegati，E. Gomes，N.S.佩雷拉E. Guerra，P. Meirelles，CADV：一种用 于 代 码 注 释 分 发 的 软 件 可 视 化 方 法 ， Inf.Softw。 技 术 -不 。 154（ 2023）107089，http://dx.doi.org/10.1016/j.infsof.2022.107089，URLhttps://www.sciencedirect.com/science/article/pii/S0950584922001987。[3]W. Hasselbring，A.克劳斯角，澳-地Zirkelbach，ExplorViz：软件可视化、理解和协作研究，Softw。影响6（2020）100034，http://dx.doi.org/10.1016/j.simpa.2020.100034，URLhttps://www.sciencedirect。com/science/article/pii/S2665963820300257.[4]S. Abilio ， P. Lima， E. Gomes， E. Guerra， P. Meirelles， Annotation VisualizerPlugin ： An IDE-Integrated Tool for Code Annotations Visualization ， Revis.deSistemas de Inf. da FSMA（30）（2022）28http://www.fsma.edu.br/si/edicao30/[5]M.博斯托克，V. Ogievetsky，J.Heer，D3：数据驱动文档，IEEE Trans.Vis。Comput. Graphics 17（12）（2011）2301 http://dx.doi.org/10.1109/TVCG。2011.185。[6]P. Lima ， E. Guerra ， P. Meirelles ， Annotation sniffer ： a tool to extract codeannotations metrics ， J.Open Source Softw. 5 （ 47 ） （ 2020 ） 1960 ，http://dx.doi。org/10.21105/joss.01960。[7]M.阿尼切湾巴沃塔角 Treude，M. Gerosa，A. van Deursen，Code smells formodel-view-controller architectures ， Empir. 软 件 。 Eng. J ， （ 2017 ）http://dx.doi. org/10.1007/s10664-017-9540-2。[8]Z. Yu，C.拜湖，加-地Seinturier，M. Monperrus，Characterizing the usage，evolution and impact of java annotations in practice ， IEEE Trans. Softw. Eng.47（5）（2021）969http://dx.doi.org/10.1109/TSE.2019.2910516