Good documentation has long been argued to be key to helping developers
write code more quickly and consistently
with design decisions, but is left largely disconnected from code. We
propose a method for active documentation, where design
decisions are made explicit as design rules and checked against code.
Developers can discover how to follow a design rule by
navigating to examples in their codebase. After editing code, developers
receive immediate feedback about which design rules
are satisfied and which are violated, notifying developers who miss
design decisions about the existence of these design decisions.
ActiveDocumentation is a tool that helps developers follow design decisions
by making the constraints of decisions explicit and checkable as AST queries.
ActiveDocumentation checks code for conformance constantly and notifies the
users about violations of decisions. It also extracts example code snippets
that follow the decisions enabling developers to use them as references and
learn how to follow the decisions.
Sahar Mehrpour, Thomas D. LaToza, Rahul K.
Good documentation offers the promise of enabling developers to easily
understand design decisions. Unfortunately, in practice, design
documents are often rarely updated, becoming inaccurate, incomplete,
and untrustworthy. A better solution is to enable developers to write
down design rules which may be checked against code for consistency.
But existing rule checkers require learning specialized query languages
or program analysis frameworks, offering a barrier to writing
project-specific rules. We introduce two new authoring techniques for
design rules: snippet-based authoring and semi-natural-language
In snippet-based authoring, developers specify characteristics of
elements to match by writing partial code snippets. In semi-natural
language authoring, a textual representation offers a representation for
understanding design rules and resolving ambiguities, which is
We implemented these approaches in RulePad.
RulePad enable novice developers to write design rules in a code-based
template by specifying the elements and conditions on each element.
While authoring rules in the tool, RulePad shows the written format of the
design rule along with extracted snippets from the actual codebase.
The former feature helps developers learn the language used in the tool and
later use the semi-natural language interface for authoring design rules.
The latter feature allows developers to validate the design rules and
make changes if necessary.
Sahar Mehrpour, Thomas D. LaToza, Hamed
Teaser (2-minute video),
Presentation (17-minute video)