SAS自动文档解析器：从源代码到发布的Code Diary

*SoftwareX 7（2018）222原始软件出版物从源代码到发布：Code Diary，SAS自动文档解析器克里斯蒂安·H Righolt*，Barret A.萨拉赫丁·蒙奇卡Mahmud疫苗和药物评价中心，社区健康科学系，马尼托巴大学，337ar t i cl e i nf o文章历史记录：2017年12月15日收到收到修订版，2018年5月16日接受，2018年关键词：文档最新解析器注释SAS代码出版物匹配a b st ra ct团队成员并不总是审查或理解所有的源代码和其中做出的决定。代码开发人员和维护人员应该有工具可以轻松地编写，维护，整理和共享源代码文档。机构的安全需求往往限制了研究人员可以在其系统上安装的软件类型。因此，有必要在已经安装的程序我们开发了Code Diary，一个用于SAS 9.3及以上版本的自动文档Code Diary提供了一种从SAS源代码生成文档的方法版权所有©2018作者.由爱思唯尔公司出版这是CC BY许可下的开放获取文章（http://creativecommons.org/licenses/by/4.0/）中找到。软件元数据当前软件版本1.0.4此版本可执行文件的永久链接https://github.com/VaccineAndDrugEvaluationCentre/code-diary-sas/releases/tag/v1.0.4;https://zenodo.org/record/1244766#.WvRli5dOmUk法律软件许可证GNU通用公共许可证v3.0计算平台/操作系统任何安装安装要求依赖关系需要SAS如果可用，用户手册链接-如果正式出版，请在参考列表N/A问题支持电子邮件VDEC@umanitoba.ca，GitHub上的问题可能会更快得到回答代码元数据当前代码版本v1.0.4此代码版本使用的代码/存储库的永久链接https://github.com/ElsevierSoftwareX/SOFTX_2018_45GNU通用公共许可证代码版本控制系统使用git软件代码语言使用SAS编译要求，操作环境依赖性无，仅SAS如果可用，链接到开发人员文档/手册N/A问题支持电子邮件VDEC@umanitoba.ca，GitHub上的问题可能会更快得到回答1. 介绍自20世纪中期以来，技术的进步导致可编程计算机的使用急剧增加通讯作者。电子邮件地址：Christiaan. umanitoba.ca（C.H. umanitoba.ca（B.A.Monchka），Salah. gmail.com（S.M.Mahmud）。https://doi.org/10.1016/j.softx.2018.07.002科学和医学研究的工具[1]。大多数医学研究项目都涉及使用统计（例如，SAS、R、Stata）或通用编程语言（例如，Python），通常开发和维护冗长复杂的程序或脚本从事这类项目的研究团队有内部分工。负责研究设计、撰写论文和传播结果的内容专家和调查人员可能没有开发来源2352-7110/©2018作者。由爱思唯尔公司出版这是CC BY许可下的开放获取文章（http://creativecommons.org/licenses/by/4.0/）。可在ScienceDirect上获得目录列表SoftwareX期刊主页：www.elsevier.com/locate/softxC.H. Righolt等人/ SoftwareX 7（2018）222-225223代码，甚至有专门知识来全面审查它，以确保它符合项目要求并实现研究目标[2]。在本文中，我们描述了软件需求，实现和使用代码日记，一个文档工具，自动生成一个报告的代码做什么，基于标准的SAS注释结构。2. 问题和背景由代码编写者（通常是统计学家、分析师、程序员或研究生）提供的源代码文档通常是代码未来用户和维护者可用的唯一书面信息根据我们的经验，源代码文档通常也是此文档通常是一个独立的文档，需要不断维护和扩展以保持与代码同步。程序员也可能做出一些小的决定，例如，如何处理缺失值，而不记得将其包括在外部文件中，也不咨询主要研究者。代码开发人员和维护人员必须有工具来简化编写、维护、整理和共享源代码文档的任务。这使研究团队能够了解代码中的所有决策，包括次要决策，并在需要时轻松调整它还使维护代码变得更容易和更快，同时提高输出保真度，直接提高生产力。源代码文档应该尽可能接近源代码本身，最好是在同一个存储库中。这降低了编写和查找文档的障碍然后文档可以使用标准的版本控制和分支工具进行发展，并与存储库的其余部分保持同步。几种文档工具（例如，Doxygen、Haddock、JSDoc、Sphinx和Read the Reader）的开发是为了支持使用通用语言的开发人员程序员使用某些约定和关键字来记录他们的代码然后，他们运行一个程序（本质上是一个代码解析器），使用预定义的模板提取和组装文档文本。然后可以将结果输出为标准格式（例如，HTML、RTF或PDF）用于共享和发布。尽管这些工具非常复杂和精细，但很少适合用于许多数据密集型医学研究项目。首先，现有的工具在描述编程构造方面更好（例如，接口签名、函数参数和返回值），而不是记录在数据准备和分析期间做出的正确解释结果所需的决策由于严格的隐私和保密规则以及对安全漏洞的担忧，研究机构限制可以安装在用于分析临床数据的系统上的软件类型也很常见[3]。在这样的封闭系统中，仅限于系统上安装的统计分析工具并不罕见在我们自己的工作中，面对这种情况，我们开发了一个文档工具，在我们的统计分析工具之一：SAS中运行。3. 要求在与程序员、数据分析师和开发人员的讨论中，我们就以下要求达成一致该工具应：1. 在SAS v9.3（SAS Institute，Cary，North Carolina）中本机运行SAS是一个数据分析软件套件，最初发布于1976年，广泛尤其用于医学研究。2011年的一项研究估计，SAS被用于美国大约40%的健康研究[4]。SAS没有为用户编写的代码提供内置的文档工具。2. 使用人类可读的非专有文本格式生成其输出，该文本格式可 在 之 后 转 换 为 不 同 的 标 准 发 布 格 式 ， 如 MicrosoftWord、HTML或PDF。3. 自动从源文件中提取文档块。文档块将被放置在相关代码块之前，以最大限度地减少维护开销，因为程序员可以轻松更新文档块以反映相关代码中的更改。与在单独的文档中维护文档块相比，这种方法应该增加程序员记住更新文档的机会。4. 能够以逻辑方式组织所产生的文档，即，文档块可以按主题分组，而不管它们在代码中的位置。例如，即使用于执行这些标准的源代码分散在单独的文件中，也应该可以提取研究受试者的所有排除和入选标准的列表5. 使程序员能够排除特定的文档块（例如，注释、提醒、任务列表），以免出现在最终输出中。6. 让你可以很容易地在源代码中找到文档。这将有助于维护和更正源代码及其文档。4. 执行我们的实现包括一个简单的语法语言（代码日记语言）和一个生 成 器 工 具 ， 产 生 一 个 人 类 可 读 的 结 构 化 文 档 包 含 的documentation- tion。4.1. 文件和文件结构Code Diary语法，松散地基于Doxygen语法，简单易学，因为它使用标准的SAS注释语法[5]，允许用户编写单行注释和注释块。代码日志单行注释以“*”开头将“*”添加一个有逻辑结构的文档比任意顺序的点的集合有用得多。为了按主题组织评论，用户使用@section.subsection语法将每个评论标记为属于特定的节或子节，并作为评论中的第一个单词输入。例如，标记为“@ methods.population. matching”的注释将放置在生成的文档中的“方法”部分、“人口”子部分和“匹配”子部分下。在生成的文档中，每个代码日志注释都被格式化为单独的项目符号。这对于简洁的文档很有用，可以快速阅读并轻松扩展为报告或手稿的全文方法部分。请参阅下面的说明，以一个示例SAS文件与代码日记的意见。4.2. 文档生成器作为SAS宏实现的文档生成器与所需SAS脚本的文件路径一起解析器- -224C.H. Righolt等人/SoftwareX 7（2018）222递归地处理提供的脚本和它包含的所有脚本1当程序员使用一个主脚本时，这个过程会更容易，所有其他项目的脚本都包含在这个主脚本中。对于文本解析，我们的实现依赖于SAS中实现的Perl正则表达式[6]。我们发现这种方法提供了足够的灵活性，不需要实现我们自己的文本扫描器和解析器。生成器将生成的注释输出为一个简单的文本文件，该文件使用广泛采用的Markdown语言进行结构化，就Markdown是一种轻量级的人 类可读标记语言 ，可以 使用几种现有的 工具（如Pandoc）轻松转换为许多标准格式[7]。我们还在SAS中创建了一个简单的markdown到html的转换器，它允许在不允许安装外部工具（如pandoc）的封闭系统上快速预览生成的HTML文件。生成器生成两种不同类型的输出文件：一种用于程序员，另一种用于研究团队的其他成员第一个文件包含程序员需要的附加信息（SAS脚本文件路径和行号），以便轻松更改注释和相关代码。第二个文件不包括脚本文件路径和行号。此外，用户还可以从生成的文档中排除特定的部分，如任务列表第二份文件旨在以适当格式与其他团队成员共享4.3. 例如请 参 见 project_main.sas 演 示 以 获 得 说 明 性 的例 如 ：https://github.com/VaccineAndDrugEvaluationCentre/code-diary-sas/blob/v1.0.4/demo/project_main.sas ， 使 用 所 包 括 的 脚 本generate_documentation. sas 调 用 文 档 解 析 器 本 身 。 脚 本project_main.sas是演示的主脚本，应该运行它来重新生成输出，脚本本身包括该文件夹中的其他几个文件。输出文件是output-for-all.md、output-for-all.htm和output-coder.md。(See README.md获取更多详细说明。）在节中使用别名是为了在适当的情况下保持关键字的简短。由于SAS对数据集名称的限制，关键字应限制为25个字符，并以字母开头。顺序列表覆盖默认顺序（在源代码中出现）。使用负数覆盖此默认顺序，3在2之前排序，等等。标题列表可用于定义节标题名称。擦除列表用于从最终文档中删除某些部分，这些部分旨在分发，这是示例中的“任务列表”（todo关键字）和regex部分。4.4. 使用代码日记可以被合并到现有的和新的代码库中。若要在项目中使用它，请确保所有代码都是从中央主文件。然后，可以使用generate_documentation.sas文件（类似于演示https://github.com/VaccineAndDrugEvaluationCentre/code-diary-sas/blob/v1.0.4/demo/generate_documentation.sas）根据以下内容 根据项目需要。代码日志注释最好在开发代码时编写，但也可以追溯添加。运行main，同时包括gener-ate_documentation.sas和code_diary.sas，然后将生成项目文档，并在每次调用代码时更新它1 当前版本的Code Diary还可以从SAS main读取通过Stata-main运行的Stata脚本可以将其扩展到从SAS内部调用的任何5. 讨论据我们所知，目前还没有基于SAS的文档生成工具具有与我们在这里描述的工具类似的功能。Code Diary对于无法安装外部软件的系统特别有用，因为所有源代码都以SAS脚本的形式提供。代码内文档本身并不新鲜。例如，Doxygen是一个成熟的代码生成器，具有广泛认可的注释风格[8]。Doxygen，像大多数其他代码生成器一样，然而，开发用于为程序员提供文档，而CodeDiary旨在为研究人员和研究结果的其他用户提供文档，这些用户可能是程序员也可能不是程序员。这种微妙但重要的差异要求使用研究人员熟悉的概念和结构来组织输出，尽管源文档被分散在多个脚本中。识字编程[9]已在SAS中实现，作为SASwave [10]的一部分。然而，SASWeave是通过shell脚本实现和运行的;对于没有shell访问权限的用户，我们的实现在SAS中原生运行许多SAS用户可能完全控制他们的系统;像我们这样的计算环境具有有限的访问权限和用户控制权，以采取所有可能的保护措施来保护个人健康信息的机密性。我们相信使用代码日记可以帮助-这是研究结果的标准，因为它鼓励分析师在他们的SAS脚本文件中记录重要的数据管理和分析决策更好地理解分析师所实施的方法可以提高方法描述的可靠性，减少报告流程中的错误，从而更准确地解释和报告结果。它还可以方便其他分析师使用相同或不同的数据集复制分析Code Diary没有图形用户界面旨在供熟悉脚本和命令行界面的用户使用由于SAS环境的限制，Code Diary还有其他限制每个关键字都是数据集名称的一部分，其中包括7个额外的字符。这些关键字被限制在25个字符内，因为SAS数据集名称的内部限制为32个字符. 2这些限制目前还没有妨碍我们使用代码日记，但如果需要，可以修改代码该工具符合我们的所有要求，并且没有已知的bug。目前，我们没有计划扩展此工具，除非需要进行标准维护。一些用户可能会从SAS内部调用其他程序，他们可能希望将来也能够阅读源代码。此工具的最新版本以及几个相关工具可以从github.com/VaccineAndDrugEvaluationCentre/code-diary-sas下载。虽然我们开发这个工具时考虑到了医学研究人员，但这个工具并不是他们的专属。6. 结论本文中介绍的工具提供了一种更简单的方法来从SAS源代码生成文档。这消除了在完成的内容和报告的内容之间的转换期间的几个最终，这提高了生产率，因为维护代码的开销较低，同时提高了输出保真度。2 代码日记允许用户使用别名和节头来缩短文本中的关键字，同时保持对实际节及其标题的完全控制，包括空格和特殊字符的使用。利益冲突C.H. Righolt等人/ SoftwareX 7（2018）222-225225[3]马斯特斯·K 在：霍伊特RE，编辑。卫生信息学伦理学。健康信息学，信息学教育;2014。提交人声明，他们没有利益冲突。作者CR设计并编写了源代码。CR和BM设计了注释语言。SM开发了这个概念。所有作者都撰写了手稿并批准了最终版本。引用[1] 威尔逊湾宏观：科学家如何真正使用计算机？美国科学2009;97：360-2.[2] Joppa LN，McInerny G，Harper R，Salido L，Takeda K，Hara K，Gavaghan D，EmmottS. 科学软件使用中令人不安的趋势 Science2013;340：814.[4] Dembe AE，Parabel JS，Geist LC.卫生服务研究中使用的统计软件应用：对美国BMC Health Serv Res 2011中已发表研究的分析;11：1-6。[5] Delwiche LD，Slaughter SJ.小SAS书：入门。第5版Cary：SASInstitute;2012.[6] 科迪河An introduction to Perl regular expressions in SAS 9，Proceedings ofthe 29th annual SAS users group international. 2004年[7] MacFarlane J. Pandoc：a universal document converter，Berkeley，2013.[8] 拉拉米湾 鲍勃对多氧的简明介绍，技术报告，可视化和交互式计算组。威尔士，英国：斯旺西大学计算机科学系;2007年（在线提供）2011年。[9] KnuthDE.识字编程。 ComputJ 1984;27：97-111.[10] Lenth RV ， Højsgaard S. SASWeave ： literate programming using SAS ，2007，19，2007，20.