利用注释促进代码理解

文献标题

Using Annotations for Sensemaking About Code

文献信息

• 主题领域: 软件开发中的注解工具及代码理解
• 关键词: 注解工具, 轻量级笔记, 软件工程, 代码理解, 感知构建, 调试, 开发者工作流, 信息外部化

研究背景与问题

• 发现的问题或挑战:

  1. 开发者在理解和调试代码时需要处理大量信息，包括任务目标、感兴趣的代码位置、代码行为的问题和假设等；
  2. 编程任务可能涉及跨多天的复杂工作，且开发者需要保持任务上下文，面临中断时恢复状态困难；
  3. 现有工具（如代码注释和外部笔记）在支持这些信息外部化和追踪方面存在不足，例如易丢失、缺乏上下文联系，并可能导致代码混乱。

• 重要性: 高效的信息管理对于软件开发的成功至关重要，能够帮助开发者更快地理解代码功能、减少认知负担，并在任务中有效协作。

• 研究动机与相关工作:

  • 代码和任务注释通常用于缓解问题，但存在以下缺陷：
    • 注释可能必须清理以防混乱；
    • 某些场景无法使用注释（如外部库代码或不允许对源代码进行更改）。
  • 开发者倾向于使用外部工具和笔记，但这些方法通常未与代码充分联结，易引发信息断层。

解决方案

• 提出的方法或解决方案: 开发并提出轻量级代码笔记工具——"Catseye"。该工具允许开发者在代码的上下文中使用注解进行信息外部化，同时不改变源代码。

• 创新点:

  1. 注释功能超越传统代码注释：
  • 支持跨语言的统一注解语法；
  • 可绑定至任意文本或代码范围；
  • 支持线程对话以追踪开发者反馈和答案。
  1. 新增功能特点：
  • 轻量化版本管理；
  • 系统输出关联与搜索功能；
  • 可暂存的“钉住”注释，便于跨代码片段导航。

• 实施步骤与关键技术:

  1. 注解创建: 使用快捷键、菜单或命令栏选择代码片段创建注解；
  2. 注解功能:
     • 多位置锚点创建；
     • 回复系统；
     • 快速导航；
     • 代码快照；
     • 搜索功能；
  3. 技术实现:
     • 使用 TypeScript 和 React 开发；
     • 依托 Visual Studio Code API 完成集成；
     • 利用 Google Firestore 保存注释数据。

研究成果

• 具体成果:

  1. 提出了 Catseye 工具，并嵌入到 Visual Studio Code 编辑器中；
  2. 通过实验证实 Catseye 在开发者调试任务中的有效性，帮助开发者更轻松外部化信息。

• 与现有解决方案的优势:

  • 注解不修改源代码，不会影响代码运行；
  • 可灵活适应开发者个性化信息需求；
  • 提供便捷的导航和任务追踪功能；
  • 整合与上下文相关的信息以提高实效。

• 实验或评估结果:

  • 使用 Catseye 的参与者在调试任务中的成功率显著高于对照组；
  • 平均注解互动频率约为对照组的两倍，表明注解促进了信息的回访和使用；
  • 参与者显著减少了处理任务时的认知负担，且能够更好地标记和追踪信息。

• 局限性与未来方向:

  • 局限性：
    • 实验任务为人工设计的代码库，未涉及真实工作场景；
    • 不支持图形输出和更复杂的互动方式。
  • 未来方向：
    • 加强与 GitHub 集成以支持协作开发；
    • 优化注解与代码版本更新管理；
    • 扩展支持其他媒体形式的信息捕获，如添加图表或截图。

这篇研究首次展示了代码注解工具如何充当开发者的思维空间，作为调试、感知构建和信息外部化的重要工具。研究提供了对工具设计及开发者信息需求的深刻理解，具有重要的实用价值与学术意义。