There is a rule in good industrial design that I learned from taking apart old appliances with my father as a kid. If you need instruction manual to understand what the knobs do, the entire design failed. The dishwasher should tell you which knob washes the glasses and which one heats the water. Not through labels or documentation, but through how it is built and arranged on the front panel. Good industrial designers make the function obvious from form alone.

Software has this problem in spades because we treat code as a special kind of language that requires a dictionary. But what if we applied the appliance design test to our APIs instead? A REST API with endpoint names like /users/123/preferences/notification/email/subscriptions/priority does not tell you any more about what it actually does than reading the function name process_user_notification_preferences_by_email_priority_level. The first one communicates through its structure as a resource tree. The second needs explanation.

I have seen this pattern repeat across every codebase I have worked in. The ones where developers could look at a class or module and understand what it does without opening any test file share a design instinct. Functions are named for what they act upon, not how they achieve the result. Config objects follow the shape of the data they control rather than some internal implementation detail. The code reads like a table of contents for what the system does rather than a technical manual for how to wire it up.

The counterargument always lands on the same point: software is too complex for this to work. And it is true that you can make any system opaque through enough layers of abstraction. Abstraction libraries build for edge cases nobody encounters while adding nothing for the 99 percent of real use. But complexity has never been an excuse for poor structure. The best database designs in the history of computing were complex and still readable because someone understood the difference between complexity of implementation and complexity of form. A well-designed SQL parser is technically complicated but intuitively obvious.

The lesson for software is not to avoid documentation entirely, but to treat it as a design artifact. Write docs before you write the code they are documenting. If you cannot explain what a function should do in two sentences without technical jargon, you will struggle to write good tests for it and even worse code will follow from that confusion. The same principle applies to public APIs, configuration schemas, and data structures. Documentation is not a secondary concern layered on top of working code. It is the first draft of the design itself.