Sometime after 2008 or so, I started telling software crafters that I was coaching that I have a guideline for code quality: “Don’t make me think.” Often I used the phrase to reference one of the many well-known code smells. Recently, I wondered where I first learned that expression. Unfortunately, online searches are dominated by Steve Krug's 2000 UI/UX book (with editions in 2005 and 2013) by the same name.The earliest use that I could find of “Don’t make me think” as applied to code quality is a blog post from 2011, If you know of an earlier use, please get in touch.
As I thought more about "Don't make me think", I've come up with many examples. Here's my list so far. What's your favorite?
- Have a readme that tells me how to run tests and install and run your application
- Use a test naming convention that gives the action, initial state, and expected state.
- Name things well
- When possible, use the names that are the same as in the business domain
- No commented-out code
- No comments, except to explain something that you have to do in an unexpected way (Debunk “good” comments)
- Unless you squash, have meaningful commit messages. If you squash, have meaningful merge messages.
- Write short methods
- Write with idiomatic use of your language
- Don’t write “clever” code
- Don’t over architect or over generalize
- Have sufficient types and amounts of automated tests
- Maintain your tests as you maintain the rest of your code
- Methods should have few arguments, and probably no boolean arguments.
- The interface of a class should “hang together” without methods that “don’t belong”
- Avoid “primitive obsession”
- Find solutions besides switch statements
- Don’t go crazy with inheritance. Prefer composition.
- Use a rich domain model, not an anemic one.
- Avoid conditional nesting
- Avoid subclassing unless you need all (or most) of the parent class (avoid Refused Bequest)
- Declare things where they are used.
- Arrange Act Assert
- One assert/concept per test
- Avoid double negation
- Use a Formatting Convention
- Short feedback cycles
- Don’t mix levels of abstraction
