Codetations: Rich, Granular, and Maintainable Annotations for Evolving Code

Abstract

Developers accumulate rich contextual knowledge about their code (e.g., design rationales, edge cases, worked examples) that does not fit in source files and goes stale when kept in separate documents or in human memory. We present Codetations, a VSCode extension enabling persistent, interactive annotations on arbitrary code spans without modifying the underlying file. A novel hybrid annotation anchoring method combines editor tracking for local edits with LLM-based semantic matching for offline changes, keeping annotations stable as code evolves. Annotation tools are modules sharing a minimal API for document access and state management. We demonstrate that this API is expressive enough to support multimedia embedding, automatic documentation maintenance, and external tool integration. In initial user studies with nine experienced developers, we found that attachment behavior matched their expectations. The diverse tools also enabled developers to imagine a variety of domain-specific use cases for annotations, particularly for validating and managing LLM-generated code. We discuss how a lightweight annotation layer can preserve contextual knowledge and open up a novel design space of developer-defined annotations.

BibTeX

@inproceedings{2026-uist-codetations,
  author     = {Misback, Edward and Jun, Eunice and Vank, Erik and Tatlock, Zachary and Tanimoto, Steven},
  title      = {Codetations: Rich, Granular, and Maintainable Annotations for Evolving Code},
  year       = {2026},
  month      = nov,
  booktitle  = {Proceedings of the 39th Annual ACM Symposium on User Interface Software and Technology},
  articleno  = {162},
  numpages   = {11},
  series     = {UIST '26},
  publisher  = {Association for Computing Machinery},
  url        = {https://doi.org/10.1145/3830398.3830552},
  doi        = {10.1145/3830398.3830552}
}

📝 publications index