标签：#readability

(The following example is fictionalized.) A notification template feature shipped six months ago. It let each tenant customize the messages sent to their own customers without requiring a back-end change every time the wording changed. The code reviewer could tell the design was hard to follow, especially the path from template to rendered value. But "this is hard to follow" is difficult to turn into a concrete objection when the feature works, the tests pass, and nothing is obviously unsafe or wrong. The design risk was real, but there wasn't an obvious bug to point to. QA signed off, and the feature went into production. Then a bug report came in: one customer had received a notification containing another customer's information. Somewhere in the notification pipeline, the system was leaking PII. At first, the fix sounded small: make sure notifications only render data belonging to the intended recipient. Then the assigned developer, who wasn't the original author, started looking for the place to make the fix. The templates were stored in the database. There were six template types, and each one populated its real values in a different part of the codebase. Some values came from customer-facing records, some came from internal workflow state, and some came from template-specific logic. The placeholder-to-value mapping lived somewhere else. Email and SMS channels shared part of the rendering path, but not all of it. Before the developer could decide where to fix the leak, they had to answer a more specific set of questions: Which placeholder rendered the wrong value? Where did that value come from? Which template types could use that placeholder? Did email and SMS resolve it the same way? What evidence would show that the leak was fully contained? The system was hard to change because it made the behavior hard to understand. What the developer needed was not just "clean code." They needed trustworthy signals they could use as evidence to answer harder questions: w