> at best, clear code tells you what it does. This depends a lot on what you mean by "clear" code! You can write higher-level code with abstractions that empha

> at best, clear code tells you what it does. This depends a lot on what you mean by "clear" code! You can write higher-level code with abstractions that emphasize the what rather than the how and you can write code that explicitly captures important additional information like invariants. Personally, I've found aiming for that works better than writing code where the "how" is clear at the expense of the "what" so that readers don't lose the forest for the trees. I am not sure I'm explaining the difference well—it would benefit from examples that I am too tired to provide right now—and documentation is still useful even with higher-level code, but my point is that code absolutely can and should clearly reflect many of the things you would also cover in documentation.