README文件风格与内容的代码审查

文献标题

Linting Style and Substance in READMEs

出版信息

• 主题领域: 通过可定制的代码检查工具提升README质量。
• 关键词: README, 代码检查, 文档质量, 领域特定语言, 大型语言模型, 可访问性, 定制化, 用户研究, 自动化, 软件文档。

背景与问题

• 问题/挑战: 现有的文档检查工具主要集中于表面层次的内容，如风格、语法和格式，无法解决更深层次的领域特定和语义问题，例如可访问性、语气和内容完整性。
• 重要性: README对于软件的采用、可用性和协作至关重要。写得不好的或不完整的README会为用户和开发者设置障碍，降低项目的成功率和可访问性。
• 动机与相关工作: 之前的研究探讨了文档质量和代码检查工具，但这些工具局限于预定义的固定规则。像markdownlint和Proselint这样的工具专注于语法和风格，但缺乏针对领域特定需求的灵活性。本文在这些工作的基础上，通过结合编程逻辑和基于LLM的方法，解决了风格和内容两方面的问题。

解决方案

• 提出的方法: LintMe，一个可定制的Markdown代码检查工具，使用领域特定语言（DSL）定义检查规则。它结合了编程操作符和基于LLM的评估，解决了README质量的多种问题。
• 创新点:
  1. 将编程逻辑与LLM集成，用于评估README的语法和语义方面。
  2. 提供一个轻量级DSL，用于创建适应特定领域和用户需求的可定制检查规则。
  3. 支持用户定义规则，实现对多样化文档标准的灵活适应。
  4. 将代码检查应用于非传统领域（如烹饪食谱），展示系统的表现力。
• 流程与关键技术:
  • 用户使用支持21种操作符的DSL创建检查规则，包括编程检查（如链接验证）和基于LLM的评估（如语气分析）。
  • 规则可以通过基于网页的操作界面或CLI进行编写、定制和执行。
  • LintMe为不同领域（如软件库、数据集）提供预设，并支持规则的迭代优化。
  • 评估包括用户研究、LLM比较，以及在食谱等其他领域的应用。

结果

• 具体发现:
  • LintMe比单纯使用LLM发现了更多问题，平均每个README检测到25.4个问题，而自由提示（free-prompt）和提供规则（rules-provided）分别为9.6和7.25个问题。
  • 用户研究（N=11）表明，参与者认为LintMe在发现问题、维护标准和定制规则方面很有帮助，但也提到有一定的学习曲线。
  • 在食谱中的应用表明，LintMe能够强制执行风格指南，并检测跨领域的系统性规则违规。
• 相较基线的优势:
  • LintMe在发现问题方面优于单纯的LLM使用，尤其是在语气、客观性和可访问性等细微领域。
  • 与传统代码检查工具不同，LintMe支持深度定制，并评估风格和内容两方面。
• 实验/评估:
  • 用户研究：参与者使用LintMe检查并定制自己README的规则。
  • LLM比较：将LintMe与基于GPT的模型（有无预定义规则）进行测试。
  • 表现力案例研究：将LintMe应用于烹饪食谱，展示其适应非README领域的能力。
• 局限性与未来工作:
  • 由于操作符如customCode和execute的存在，可能被恶意使用。
  • 对LLM的依赖带来了非确定性和幻觉的风险。
  • 评估范围有限（如LLM比较的样本量较小，特定领域）。
  • 未来工作包括扩展到完整的文档网站、改进可用性，以及探索分层错误聚合。

总结

LintMe是一种新颖的代码检查工具，通过结合编程逻辑和基于LLM的评估，解决了README中的风格和内容问题。它允许用户使用轻量级DSL创建和定制规则，使其能够适应多样化的领域和社区标准。评估表明，LintMe在发现细微问题方面优于单纯的LLM使用和传统检查工具。尽管存在如LLM依赖和可用性挑战等局限性，LintMe展示了将代码检查扩展到复杂文档和文化介导的文本领域的潜力。