software-design
Software Design
Reduce the amount of information a developer must know, and make the remaining information obvious. Software complexity is whatever makes a system difficult to understand or modify—especially when essential information is hidden or distant. The goal is information locality: the information needed to understand and modify a part of the system is colocated and easy to find.
Design for the reader, and the reader is a fresh session: the next engineer, a
reviewer, or an agent with no memory of this conversation. Whatever the author
knew — the request, the rejected alternatives, the failure that shaped the
fix — survives only if it lands in the repository: code, names, comments,
contracts, tests, or the nearest scoped AGENTS.md. Judge a design by how
much a fresh reader must gather before they can change it safely.