# Architecturally Evident Coding Style

**In short:** An architecturally evident coding style shows architecture rules in the code itself, through package layout and naming conventions. Automated tests, such as ArchUnit for Java, can then check that the code follows those rules.

## Explanation

Some architecture rules live only in documents or in people's heads. An architecturally evident coding style moves them into the code. Two means appear in practice: package structure and naming conventions.

**Layers as packages.** A layered architecture splits a system into layers and states how they may interact (see Layered Architecture). If each layer maps to a package pattern, the layers are visible in the folder structure. The Waltz project did this. It defined layers simply as matching package patterns.

**Conventions in names.** Names can carry rules too. Waltz agreed that methods returning collections are named `findXYZ`. A reader then knows what to expect from a method before opening it.

**Checking the rules.** Conventions only help if they hold. ArchUnit is a free Java library for checking the architecture of code. It runs architecture and coding rules as ordinary unit tests, so a build can fail when someone breaks a rule. For layers, you define them by package patterns and state which interactions are allowed. Waltz used ArchUnit this way and found it more concrete than a style guide. It also checked the naming convention above with the same tool.

**Legacy code.** Old projects may have too many violations to fix at once. ArchUnit can freeze the known violations. The tests then reject any new ones. This limits drift step by step, without a big cleanup first.

## Example

A team builds an online shop in Java. They put code in three packages: `web`, `service` and `persistence`. They agree that `web` may call `service`, and `service` may call `persistence`, but never the other way around. They also agree that any method returning a list of orders starts with `find`.

They write these rules as ArchUnit tests. If a developer later makes `persistence` call `web`, the build fails and the team sees the problem at once.

## Trade-offs

The facts here cover enforcement only, so the trade-offs are limited to that. Rules written as tests need upkeep like any other code. Package patterns and naming rules must be defined and agreed by the team. Tooling such as ArchUnit targets Java code. Freezing violations in a legacy project stops new ones but does not remove the old ones.



## Checks

- Layers are defined as package patterns, and the allowed interactions between them are stated.
- Architecture and coding rules run as automated unit tests in the build.
- Naming conventions, such as the name pattern for methods that return collections, are checked automatically.
- For a legacy code base, existing violations are frozen so that no new ones are added.

## Related

- [Layered Architecture](https://arc.fuet.ch/concepts/styles-patterns/layered-architecture.md)
- [Layers Pattern](https://arc.fuet.ch/concepts/styles-patterns/layers-pattern.md)
- [Architecture Decay](https://arc.fuet.ch/concepts/fundamentals/architecture-decay.md)
- [Documentation as Code](https://arc.fuet.ch/concepts/documentation/documentation-as-code.md)
- [Self-Documentation](https://arc.fuet.ch/concepts/documentation/self-documentation.md)
- [Technical Debt](https://arc.fuet.ch/concepts/evaluation/technical-debt.md)
- [Modularity](https://arc.fuet.ch/concepts/principles/modularity.md)
- [Module](https://arc.fuet.ch/concepts/domain-driven-design/module.md)

## Sources

- [ArchUnit User Guide](https://www.archunit.org/userguide/html/000_Index.html) — archunit.org, accessed 2026-11-09
- [Formalising code architecture using ArchUnit | FINOS - Waltz](https://waltz.finos.org/blog/waltz/dev/2019/01/20/arch-unit.html) — waltz.finos.org, accessed 2026-11-09