Semantic integrity means that a program’s data meanings and valid states are explicit, descriptive, and consistently enforced. Without it, fields such as null, timestamps, and counters carry implicit domain meanings that every method must reinterpret. That invites semantic drift: one mistaken interpretation can invalidate the system’s behavior. section 1.3.1
Making retry states explicit
A ScheduledTask initially represents retry behavior through assignments: an incremented attempts counter with a small scheduling delay means retry immediately; zero attempts with a larger delay means retry later; zero attempts with scheduledAt set to null means abandon the job. Replacing these combinations with RetryImmediately, ReattemptLater, and Abandoned data makes the domain meaning visible in the types. Code can then test task.status() instanceof Abandon instead of guessing what null means. section 1.3.1 section 1.3.2
Semantic integrity improves a model when it:
- Names domain decisions directly instead of encoding them as combinations of flags, counters, timestamps, or nulls. section 1.3.2
- Makes valid alternatives visible so surrounding code can consume descriptive states without reconstructing their meaning. section 1.3.2
- Uses descriptive methods such as isAbandoned when a full data refactoring is unnecessary, while retaining object-oriented boundaries. section 1.3.2
Listing 1.4 if attempts is not set then it means..."
class ScheduledTask {
private Instant scheduledAt; #A
private int attempts; #A
public void reschedule() { #B
if (this.someSuperComplexCondition()) {
this.scheduledAt = now();
this.attempts += 1;
} else if (this.someOtherComplexCondition()) {
this.scheduledAt = now().plusSeconds(DELAY);
this.attempts = 0;
} else {
this.scheduledAt = null;
this.attempts = 0;
}
}
}Compare the compact state variables with the reschedule branches that assign them; the listing exposes how much meaning remains implicit. section 1.3.1
