check-legacy

First document what the code actually does versus what it claims to do, then write characterization tests that capture current behavior before changing anything. These tests detect unintended behavior changes during refactoring, even when the current behavior is wrong.

Trace the actual execution path of the affected method, audit variables for null and sentinel values, and check transaction boundaries around the change. Also search for hidden callers like scheduled tasks and event listeners that interact with the modified code.

Checked exceptions do not trigger rollback by default in Spring; you must specify rollbackFor on the @Transactional annotation. Additionally, self-invocation bypasses the Spring proxy, so @Transactional on a method called via this.method() has no effect.

A characterization test captures the current behavior of code, even if that behavior is wrong, rather than asserting desired behavior. If it fails after a change, you know behavior changed and can evaluate whether that was intentional.

Run it before modifying any legacy class, fixing bugs in old code, or refactoring — especially when code predates Spring Boot 3.x, has no tests, or contains methods longer than 50 lines. It is also essential when a fix worked locally but broke in production.