Clear Is Better Than Clever
I read a PDF from Dave Cheney today titled Clear Is Better Than Clever. I really liked it, so I took some notes. Without further ado:
Software engineering is what happens to programming when you add time and other programmers. – Russ Cox
We need to read each other’s code because we have to work together. We need to read and understand each other’s work, so that we can maintain it and improve it over time. This is the distinction between “software programming” and “software engineering”.
Code is not literature. We don’t read code, we decode it. – Peter Seibel
We call it source code, not source literature.
- Our most common complaint in a foreign codebase is that the code is “unreadable.”
- When we say this, what we really mean is that we don’t understand it.
- Readability is a subjective concept. Clarity is not readability.
- When something is complicated, it should look complicated.
If something unusual is happening, leave evidence for the reader. – Brian Kernighan
- Keep to the left.
- Favor guard clauses and preconditions. Encourage the success path to read straight down the page, rather than increasingly indented in conditional blocks. At each point in the function, you know that a growing set of preconditions is true.
- “Line of sight” coding.
- Just to reiterate that clarity is different for readability. You are writing your code for others (and you in the future) to both read and understand. The first step toward maintainable code is communicating the intent clearly.
- Complexity: being afraid to make a change because it may break some other part of the program, especially if you don’t understand or know how to fix that other part.
- Definition: how much time you spend doing useful work versus not.
- Arrange your code to minimize the effort it takes both maintainers and newcomers to get useful work done. Also minimize the amount of “drudgery” work required in the code base.
- Clear, helpful error messages. Fast tooling. Standardized and agreed upon organization (I cannot stress how much more productive you are when you know exactly where to find what you’re looking for).
If software cannot be maintained, it will be rewritten.