adam bien's blog

Java Verbosity Is Cheap, Ambiguity Is Expensive 📎

A clarifying question from the agent costs a full round trip. A type declaration costs a handful of tokens. Verbose Java is the cheaper option.

  1. Ambiguity costs a turn, verbosity costs tokens. A wrong guess costs a full extra round trip. A declared type costs a few tokens in every turn that follows, and prevents the guess.
  2. Constraints are machine-verifiable. javac is the cheapest judge in the loop. A type error costs milliseconds and no tokens. In a dynamic language the same mistake surfaces at runtime or in a review turn.
  3. Code is the only context the compiler checks. A sealed interface survives across sessions and developers. A prompt or an instruction file like CLAUDE.md, AGENTS.md or SKILL.md is re-sent on every session and never enforced.
  4. Annotations declare rules in a single word. @NotNull, @Size, @Transactional, @Path, @Inject: each states a constraint the agent would otherwise infer from the method body or ask about. Standard annotations compress further, because @Path maps to spec behavior the model has seen thousands of times. An in-house framework has to be explained in every session.
  5. Names lead from the requirement to the code. A requirement that mentions the customer email leads the agent to findCustomerByEmail with a single search. A method named get forces it to read the implementation. In a BCE package structure (boundary, control, entity), the package name tells the agent the layer from the import alone. The compiler never checks names, so a misleading name misleads as reliably as a descriptive one guides.
  6. Intent is not ceremony. Records, sealed interfaces, generics, final, checked exceptions, annotations and descriptive names carry semantics. Getters, setters and Impl suffixes carry nothing.

Verbose code consumes output tokens and context window. A clarifying question consumes a full round trip on top of both.

A rule from 2013, How To Comment With JavaDoc, predates coding agents and still applies: the WHAT goes in the name, the HOW in the code, and the WHY in the comment. The WHY is the only context the agent cannot derive from the source, so a JavaDoc on a non-obvious decision keeps the rationale in the repository instead of in the prompt. The conventions that made code readable for the next developer make it unambiguous for the agent.