Semantics are what data and operations mean in a domain, not merely the values or syntax used to represent them. A number becomes data when it is about temperature, sales, elapsed days, or something else; that context immediately raises questions about units, range, fidelity, and use. Good representations put those answers into code rather than leaving them as folklore in someone’s head. section 2.3 section 1.3
Start by looking for a mismatch between what the team knows and what the type permits. `String id` may be intended as a UUID but accepts countless non-UUID strings. Likewise, a generic task with retry fields can suggest that a scheduled task needs retry information before it has even run. Splitting such cases into types such as scheduled, failed, completed, or running makes the domain distinctions visible. section 1.2 section 1.4
Make a method say what it does
A `void reschedule()` method hides both its input and result. A function shaped as `RetryDecision reschedule(FailedTask task)` states that rescheduling applies to a failed task and produces a retry decision. Pattern matching can then select among retry-now, retry-later, and abandoned outcomes directly from that data. section 1.4
Names and documentation improve readability, but they do not stop invalid values from entering or losing their meaning during later computations. Construction-time validation can enforce invariants such as a nonnegative day count or a valid measurement range. Stronger domain types carry distinctions beyond construction, so unrelated doubles, strings, or units are harder to mix accidentally. section 3.2.1 section 3.2.2 section 3.2
Listing 1.14 Which tells you more about what the method does?
public void reschedule(){} #A
// versus
public static RetryDecision reschedule(FailedTask task) { #B
// ...
} Compare a behavior-hidden instance method with a data-in/data-out signature that exposes the domain operation’s meaning. section 1.4
Semantics also guide larger boundaries. Keep domain code speaking in domain operations such as upsert rather than inserts and updates, and accept well-modeled inputs rather than HTTP or JSON. Adapters can own those external details, leaving the core easier to reason about, test, and change when dependencies change. section 10.4.6 section 10.4.8
This is an iterative design discipline, not a demand to replace every object. When a representation permits nonsense, revise the model instead of spreading defensive checks. Balance clearer semantics against the cost of reshaping legacy code and the ergonomics developers need to use the types consistently. section 4.1.3 section 5.4 section 5.5



