This guide describes how to design frameworks, annotations, aspects, and integration surfaces in a style that favors narrow contracts, explicit wiring, caller-owned lifecycle, and thin adapters over third-party APIs. It is a companion to any general code-style guide: this document is about shape and design decisions, not formatting or naming.
Drop this file into a project where you want code generators and contributors to produce frameworks that compose cleanly rather than frameworks that try to own the runtime.
- Narrow contracts. A framework answers one question well. If it is answering two questions, it is two frameworks sharing a name.
- Explicit over implicit. A reader should be able to trace behavior from a line of code to the thing that produces it, without following auto-configuration, classpath scanning, or annotation-magic chains.
- Caller-owned lifecycle. Startup, shutdown, resource ownership, and replacement policy belong to the application unless the framework is explicitly about that concern.
- Thin adapters, not meta-frameworks. When integrating with a container, transport, or external system, adapt — do not wrap and rename.
- Fail fast, fail loud. Bad wiring should surface at startup with a clear message, not as silent drift at request time.
- A direct path must always exist. Whatever convenience a framework offers — annotations, builders, DI glue — the programmatic direct path stays first-class.
A framework in this style is a small, focused mechanism that answers one integration question cleanly. It is not a platform, not a container, not an application skeleton.
Structure the framework as layers with distinct responsibilities:
- API / contract — the interfaces, markers, and value types callers depend on. Small and stable.
- SPI / extension — the interfaces an implementor satisfies to plug in. Sometimes the same types as the API; sometimes a separate surface.
- Runtime / implementations — one or more concrete implementations, each a separate module or package when possible.
- Integration adapters — container glue, factory beans, XML schema support, assembly helpers. Live in a clearly labeled subpackage so consumers can see they are optional.
A library using the framework should be able to depend on only the API module. Applications select and depend on runtime implementations explicitly.
If several related questions share a problem space but each deserves its own vocabulary (for example, rate limiting, load balancing, pooling, and naming all live in "resource management"), ship them as sibling sub-frameworks that share a package root rather than as one framework with modes. Shared vocabulary hides divergent contracts.
- Applications wire implementations by direct construction, factory, or explicit name lookup.
ServiceLoader, classpath scanning, and auto-configuration are not first-class extension mechanisms in this style. They are acceptable only when the framework is explicitly in that business, and the behavior is documented.- A framework that routes by name (for example, a registry of named emitters) binds those names at assembly time, not at runtime from ambient state.
- Make configuration visible in the type system: constructor parameters, setters, or builder methods.
- Avoid configuration schemes whose inputs come from annotations, system properties, or environment variables unless the framework is explicitly a bridge to those surfaces.
- Document every parameter's default in the constructor or field initializer, not in prose elsewhere.
When a framework genuinely needs a registry — for loggers, contexts, metric meters, or
other well-known names — prefer a static class with explicit register / unregister
and deterministic lookup.
- Do not hide the registry behind auto-discovery.
- Do not mutate the registry from static initializers of unrelated classes.
- Do not let the registry become a global mutable scratch space; keep it to the named surface it was designed for.
A module's module-info.java states its contract in a form the compiler and the runtime
enforce. requires static is how an optional integration is expressed: the dependency is
optional in the POM and static in the descriptor, and neither says more than the other.
Reflective access is granted by a qualified opens … to naming the framework that needs
it, or by an unconditional opens only for packages whose resources are loaded by path.
Never declare an open module.
An annotation's job is to declare intent in a location where a separate tool (aspect, annotation processor, reflection-based utility) can find it. Annotations do not carry behavior; they carry labels.
Introduce an annotation when:
- A separate tool needs to locate the annotated elements (an aspect, a processor, a validator).
- The declarative form is a genuine improvement over a programmatic call at that site.
- The semantics of the label are obvious from the name.
Do not introduce an annotation when:
- The effect could be achieved by a method call at the same site with equal or better clarity.
- The annotation would only save a few characters.
- The annotation's behavior depends on ambient configuration the reader cannot see.
- Keep parameter sets small. Annotations with many parameters are usually doing too much.
- Parameters should be primitives, strings, class literals, enums, or simple nested annotations. Avoid parameter types whose semantics depend on external state.
- Choose retention and target deliberately. A
RUNTIMEretention is a runtime cost; pickSOURCEorCLASSwhen that is enough.
- Marker annotations are legitimate: they say "this element participates in some concern." The concern is implemented elsewhere.
- Metadata annotations carry parameters describing shape: expected types, validation bounds, format strings. The reader carries those parameters out.
- Behavior annotations — annotations that promise to do something on their own — are almost always a mistake in this style. If the annotation implies behavior, the behavior lives in a named aspect, processor, or utility that the reader can trace to.
Every declarative annotation should have a programmatic equivalent. A caller who does not want to pull in the annotation processor, the aspect weaver, or the reflective scanner must have a direct call that produces the same effect.
Aspects are justified for cross-cutting concerns that cannot be expressed as ordinary interface methods or wrappers without significant duplication: field injection, declarative transactions, instrumentation, logging advice.
- The pointcut binds a specific annotation on a specific kind of join point (a method execution, a field access, a constructor).
- The pointcut binds the annotation instance and the
thisreference directly, so the advice does not need reflection to locate either. - Pointcuts should not use wildcard class or package matches as their primary condition. That is a discovery pattern, and aspects should not do discovery.
- Keep advice small and focused.
@Aroundfor "replace or wrap the call";@Before/@AfterReturning/@AfterThrowingwhen the phases are actually different concerns. - Do not build a general-purpose aspect that switches on annotation parameters to do different things. Split it.
- If the aspect is not woven, the deployment is broken. Surface it at build or startup, not as a subtle runtime degradation.
- Do not add runtime checks that silently no-op when the aspect is missing. That hides the misconfiguration and makes the failure mode harder to diagnose.
- The annotation points the aspect at its join points. The aspect operates on what the pointcut already gave it.
- If the aspect needs to scan fields, resolve names, or walk type hierarchies, that logic belongs in a separate utility the aspect calls into — not in the advice body.
A dependency-injection container (Spring, Guice, CDI, or similar) is an optional assembly layer. The framework does not take a dependency on the container; the container is merely one way to wire the framework.
- Put all container-specific classes (factory beans, configuration adapters, XML schema
handlers) in a clearly labeled subpackage — for example,
.spring,.guice,.cdi. - The core framework imports nothing from the container.
- A consumer who does not use the container can depend on the core module and never pull in the adapter module.
When providing a Spring factory bean:
- Implement
FactoryBean<T>andInitializingBean. - Expose configuration via Java Bean setters.
- Build the product in
afterPropertiesSet()and hold it in a private field. - Return it from
getObject(). - Declare
getObjectType()andisSingleton()explicitly.
The same shape applies, adapted, to other containers.
- The factory bean must not be the only way to construct the product. The constructor or builder it delegates to is public and usable directly.
- Documentation covers the direct path before or alongside the container path.
A custom exception hierarchy earns its keep through shape, not naming. A base class that renames the JDK hierarchy without adding value is noise.
- A printf-style constructor (
String format, Object... args) that appliesString.formatat construction. This is a real ergonomic improvement at the throw site. - Preserved causes: always carry a
Throwable causethrough when wrapping. - Optional structured fields for error codes, categories, or context when those are genuinely part of the contract.
- Provide both a checked and an unchecked base when the framework has both kinds of failure.
- Use the checked base for failures the caller is expected to handle; use the unchecked base for contract violations or programming errors.
- Do not introduce parallel hierarchies that rename
IOException,IllegalArgumentException, orIllegalStateExceptionwithout structural additions. - Do not wrap every exception; wrap only when the wrap adds contract value.
- Missing providers, contradictory configuration, and impossible runtime combinations should throw at startup, not at the first request.
- Throw from constructors,
afterPropertiesSet(), or an explicitstart()method. Prefer a named exception over a bareIllegalStateException.
- A named, specific exception with a descriptive message beats a silent fallback every time.
- When a fallback is genuinely the right behavior, log it at a visible level and make the fallback path part of the documented contract — not an implementation secret.
No Hidden Retries
- Anything the framework retries on the caller's behalf must be an explicit, documented policy — configurable and visible in the API.
- Do not add "just one quiet retry" to smooth over flaky dependencies; the caller needs to know.
- Auto-configuration that wires beans from the classpath without the application opting in by name.
- Annotation-driven behavior where the code path cannot be traced from the annotation back to a named processor or aspect.
- Mega-frameworks that own multiple unrelated concerns under one package.
- Framework code that assumes a container is present at runtime.
- Extending JDK hierarchies purely to rename them.
- Hidden worker threads, hidden timers, hidden retries, hidden fallbacks.
- Optional features implemented as mandatory dependencies in the core module.
- Registries that mutate from static initializers in unrelated classes.
When designing a new framework, annotation, or aspect in this style, proceed in this order:
- Write the narrowest possible contract — the interface or type that describes the one thing the framework does.
- Add the programmatic direct path: constructor, builder, or factory that produces a working implementation without any declarative layer.
- Add the declarative convenience only after the direct path is in place. Annotations mark intent; aspects or processors implement it.
- Put container-specific glue in a labeled subpackage. The core depends on nothing from the container.
- Decide and document the exception shape: checked base, unchecked base, message format, cause preservation.
- Decide and document the lifecycle: who constructs, who closes, who replaces, who owns worker threads.
- Fail fast on misconfiguration, fail loud on runtime errors, do not silently retry or fall back.
- Verify that every declarative convenience has a non-declarative equivalent and that the two produce the same effect.
- Document the contract, defaults, and failure modes in the same place, as part of shipping the framework.
A framework, annotation, or aspect that survives this checklist will compose cleanly with others and will not grow into something that owns more of the runtime than its name suggests.