These principles extend the list in 🪄 Design Principles specifically for software.
Be pragmatic
Having a perfectly engineered solution is great, but sometimes it’s okay to have a sub-optimal approach until it holds you back too much. Premature optimization is an obvious example of this.
Prioritise simplicity
Abstractions are a great way to make code easier to reason about. You don’t have to worry about the implementation details and can just focus on the high-level concept. It’s important to keep in mind that good abstractions are amazing but bad abstractions will make your life miserable. Use them wisely.
If it’s a bad abstraction, it won’t represent the high-level concept well. This often means you need to be aware of many of the implementation details to use it. To make it even worse, bad abstractions often have a negative compounding effect on the codebase. Making everything that uses it needlessly more complicated.
Getting rid of bad abstractions in time is crucial, which naturally leads to the next principle.
Refactor ruthlessly
There are two reasons for why refactoring is valuable
- Code can always be improved
- Changing code can uncover bad design
Not refactoring enough can result in a vicious cycle:
- There’s friction when making changes
- Developers build around the code instead of changing the code
- The code becomes more difficult to understand
- There’s even more friction when making changes
🧹 You Should Refactor More Than You Think is an article that focuses on this particular principle.
Use automated tooling
The simplest example of this is formatting. It’s always better to have an automated formatting tool than expect developers to point out formatting issues in Code Reviews.
Write tools, even if you might have to throw them away later (this comes from 📝 Reading Notes - Basics of the Unix Philosophy).
Prefer building in-house
When deciding to introduce a new dependency or write custom software, err on the side of writing custom software to better learn about the problem space. Don’t hesitate to come back on this decision when it becomes clear that it’s not worth the effort to build in-house.
Manage dependencies
Avoid unnecessary dependencies, but more importantly, make sure dependencies make sense. Circular dependencies will come back to haunt you.
Write stateless code
State is hard to reason about and much more difficult to test. Of course, there will almost always be at least some form of state, but splitting that from stateless code will make it much easier to understand and debug.
Folder structure
Keep test files next to code files. All related code files should live as closely together as possible.