Embedded Architectural Decision Records

Architectural knowledge captured in architectural designs and architectural decisions is primarily created and consumed in tools made for software architects. Developers, also consuming and creating architectural knowledge, do not always use such tools; this adds to the gap between these two roles often observed in practice. Architectural erosion and knowledge vaporization are two of the consequences.

With this repository, we show how to narrow the gap with architecture domain-specific Java annotations. These annotations allow developers to reference and create architectural decision knowledge directly in code. This knowledge can then automatically be processed by other tools to provide additional integration and collaboration capabilities.

Currently, following architectural decision records are supported:

• Markdown Architectural Decision Records ("MADR") - lean architecture decision records using markdown
• Y-Statements - Sustainable Architectural Decision Records

See https://adr.github.io for more information on architectural decision records.

Examples

Example for complete embedding

@MADR(value = 1,
    title = "Implement entire business logic layer as POJO",
    contextAndProblem = "Need to select a single consistent ComponentImplementationParadigm' for entire business logic layer",
    alternatives = {"POJO", "JEE EJB", "Spring Bean"},
    chosenAlternative = "POJO",
    justification = "Because it is a company-wide policy, see http://www.iaas.uni-stuttgart.de/institut/ehemalige/zimmermann/indexE.php",
    relatedDecisions = {2, 3})
public class MADRAnnotationDemoClass {
    public int sampleBusinessLogic(String input) {
        return 42;
    }
}

@MADR indicates that the annotation used the format defined by the "Markdown Architectural Decision Record". The content is directly embedded in the annotation.

Example for a linked ADR

@ADR(1)
public class MADRAnnotationDemoClass {
    public int sampleBusinessLogic(String input) {
        return 42;
    }
}

By using @ADR(1), the annotation points to ADR 0001. The convetion is that the decisions are stored in docs/adr/ with a running number. They can be of an arbirary format, such as MADR or Michael Nygard's format, which is supported by adr-tools. Example MADRs can be seen at the ADR log of the adr-log tool.

Use in your projects

Search maven central for the latest version.

Gradle:

implementation 'io.github.adr:e-adr:{version}'

Maven:

<dependency>
  <groupId>io.github.adr</groupId>
  <artifactId>e-adr</artifactId>
  <version>{version}</version>
</dependency>

Development information

To upload to maven central, the gradle task publsihToSonatype at io.github.adr.embedded is used. Thereby the Gradle Nexus Publish Plugin plugin is used.

Related work

• Documenting Implementation Decisions with Code Annotations
  • Uses JavaDoc
  • Requires external tool to allow for auto completion