Programming Tools for Working with Design Decisions in Code

When writing code, developers make design decisions by choosing between alternatives. Subsequent work with code requires reasoning about these design decisions, ensuring their code is consistent and answering rationale questions about why they were made. While documentation might help, it is rarely updated and often incomplete and untrustworthy. We propose a new form of documentation which is active, making design decisions checkable and offering immediate feedback on violations as they occur. Active documentation helps developers reason about design decisions by offering explanations and linked code snippets illustrating how to follow a design decision. To ensure active documentation is easy to create and maintain, new ways to create and edit checkable design decisions are needed. We offer a vision for active documentation, offer evidence for its potential, describe several techniques to achieve it, and suggest future directions for programming tools to better support it.