A little while ago I started compiling lists of ideas I held dear with regard to my programming attitude and attitude. Documenting my own thoughts allowed me to examine them in more detail and review the lessons I’ve learned in my career.
I am a self-taught developer. My knowledge comes from my experience, and my experience is nothing more than a long series of mistakes and improvements. Each of these principles has a story attached where I could tell you what went wrong and how it could have been prevented.
This isn’t the stone tablet of iron-clad, unbreakable rules - this is a shared understanding of what “good” means. It’s important I communicate a common base, to know what to expect and how I work.
Hopefully when you read them you will leave with a better understanding of the values I promote and how I approach problems.
This isn’t a finite task. I am continuously improving these principles as I grow and learn.
This guide was inspired in part by the Monzo Engineering Principles.
💎Iterations over artifacts
It’s not gonna be perfect - you might as well accept it. No matter how well-thought-out a solution might seem, how complete a spec is or how exhaustive a design document is, the only way to know whether it works is to get it into the hands of real users.
Reject appeals to over-planning, and resist the urge to “just one more thing” - define a clear understanding of what’s “done”, and come back for the rest later.
🧪 Test Everything
Testing is the backbone that provides us the confidence we need to ship code. Automation in testing provides us with an ever-advancing suite of tools to provide feedback as early as possible.
Reject suggestions that relegate testing to an afterthought. Reject solutions that make testing difficult.
🤏 Make changes small, make changes often
The smaller a change is, the easier it is to reason about. The smaller a change is, the easier it is to review, understand, test, deploy and roll-back.
Big changes undermine confidence from technical teams and leave the door open to accidents.
📉 Know when to borrow
The accumulation of technical debt goes hand-in-hand with the desire to ship software quickly. Know that quick fixes, hacks and tricks have a place in the development process, but they must be acknowledged for what they are.
A well timed debt can propel us into a position of providence, where we can repay it in safety - be up-front about what risks are being taken and what the payoff is.
⚠ Solve Problems, Not Symptoms
Having a clear understanding of the problem at hand allows us to find solutions that repay technical debt, rather than perpetuate it. Break problems down until you form a deep understanding of what the issue is and how it manifests. Be prepared to walk back up the chain and ask questions along the way.
As above, quick fixes have their place, but you should know what a “full” solution looks like.
⁉ Do Not Guess
Use the scientific method when designing, optimising, and debugging.
- Don’t accept theories that don’t fit well
- Explain your reasoning and provide evidence
- Don’t be afraid of saying “I don’t know!”
📖 Write code for reading
Programmers write code, but we spend the majority of our time reading it!
Good code is concise, easy-to-follow, and can explain itself regardless of insider knowledge. Good code can show engineers what it does and why it does it that way.
Complex code is hard to understand and hard to review - the complexity is a hotbed for bugs and other unknown consequences.
🐛 Write code for debugging
It’s inevitable - your code has bugs; accept it as a fact - write your code around the idea that things go wrong:
- Use Logging & Telemetry liberally
- Don’t handle or swallow exceptions blindly
- Use comments to explain the why and not the what
⛺ Leave the camp better than you found it
Leave this world a little better than you found it. —Baden-Powell’s Last Message (1941)
Any engineer can suggest an improvement to the codebase, and no-one should feel bad for trying to make things better 💕. We should work together to promote a shared understanding of our code, and accept ideas and suggestions from everyone.