We have tech principles so that we can agree, as a team, what “good” looks like. These principles should help us to reinforce the kinds of behaviours that we want to encourage amongst each other. They should be a declaration of the teamʼs intent, both to the business and to the public.
Slow down to speed up
Validating requirements, testing, writing documentation, setting up monitoring, and communicating changes are not secondary to shipping code. Before starting to code pause to evaluate whether the problem youʼre being asked to solve is clear and valid. When coding consider how you or someone else may interpret your work in the future and how easy it is to understand, refactor, and remove. If youʼre working on systems which are used by others, think about the wider impact of the changes you make and involve those who will be affected by your decisions.
Questions to ask:
- Does this change affect any teams or systems outside of my immediate area?
- Do I need to update the readme, wiki, healthchecks, or runbook to cover this change?
- Do the existing tests adequately provide coverage of the code and describe how it is intended to behave?
Download the poster for this principle
Write code you can fix at 3AM
Making the intent of your code clear is more important than how clever it is. Make time to refine your ideas and consider how easy they are to interpret and debug. Use code comments, commit messages, and pull request descriptions to add context to the decisions your code encompasses. Integrate metrics and logging around important business logic so that health checks can be used to effectively detect and pinpoint errors. Ensuring documentation remains up-to-date might mean nobody needs to be called at all.
Questions to ask:
- Can this code be debugged easily and without any special tools?
- Could my new feature be safely contained within a feature flag?
- Are the readme and runbook for this project still up-to-date?
Download the poster for this principle
Get to the root of the problem1
Temporary hacks and workarounds will always be necessary but try to understand what the long-term solution looks like. Aim to provide information about the “complete” solution along with any temporary code changes and communicate when a full solution is still required. Always push back if you believe a short term gain is outweighed by the long-term downsides.
Questions to ask:
- Do I need to open an issue in the repo and add a ticket to the backlog to pick this issue up again later?
- Will this change require other developers to add compromises to their code?
- Does my pull request and code comments clarify the problem being solved?
Make small changes often
Deploy work in small, meaningful pieces. Keep pull requests focussed and resist the urge to squeeze in “one more thing”. Small changes are easier for your colleagues to review and are less risky to undo should anything go wrong. Incremental deployments can also enable us to learn from and benefit our customers sooner.
Questions to ask:
- Does this work cover a single change or should I split it into multiple pull requests?
- Will the reviewer of this code have all of the required context?
- Can we start to gather data or user feedback on this feature before completing all of the small details?
Download the poster for this principle
Keep things secure
Ensuring our applications and data remain secure is critical to the business and our customers so we must always prioritise actions which help to minimise risk. Take the appropriate measures for securing applications, be aware of how weʼve leaked sensitive data before, and know the process for reporting new security breaches. When bad things happen do not handle the incident alone but share it with the team so that we can all help and learn from it.
Questions to ask:
- Is this project setup with Secret Squirrel and Snyk?
- Can we avoid handling user data in this application?
- Are the dependencies for this project actively maintained and kept up-to-date?
- Is there sufficient logging to detect attacks or debug issues?
Download the poster for this principle
Favour existing solutions2
Starting a new codebase can be exciting but consider that all code will eventually need to be maintained by somebody else. Trying new tools is fun but effort will be needed to use them effectively which distracts from writing the best solution. Remember that short term gains can be outweighed by the complexity of maintaining additional tooling indefinitely. Aim to maintain only the code we absolutely need and prefer proven tools the team feel confident using.
Questions to ask:
- Does an existing component or project already offer this feature?
- Is there a reasonable off-the-shelf solution already available to install or to buy?
- Can we collaborate with another team to provide this capability?
Download the poster for this principle
Use data effectively
We are awash with analytics data but it cannot tell a complete story by itself. Where possible confirm quantitative data (the what) with qualitative research (the why) in order to gain a depth of understanding to broader patterns. Try to maintain objectivity and acknowledge your own biases by verifying and reviewing your decisions with others. Likewise, critique data when it is presented to you and ask for clarification if you believe it may tell a different story.
Questions to ask:
- Do we have any user research to back up the metrics being used?
- Are the numbers correct, validated, and being presented fairly?
- Has the measure of success for this project remained the same?
Download the poster for this principle
Treat unblocking others as your priority
If someone is stuck, helping them is an incredibly high-value use of your time: spreading knowledge and skills levels everyone up. If someone is waiting on you for a code review, think about prioritising that ahead of writing new code yourself.
Questions to ask:
- Have any of my team gotten stuck working on the same ticket for a long time?
- Am I assigned to review any new pull requests?
- Are there any open issues I can add extra context to?
Download the poster for this principle
Assume good faith3
Everybody makes mistakes but remember that we are all here to try and help with the projects we work on, not harm them. Assuming good faith does not prohibit discussion and criticism but consider that we each have a different perspective and are acting with different amounts of information. Show your good faith by clearly articulating your motives and make changes that show your willingness to compromise.
Questions to ask:
- To the best of my knowledge, do I have the full and correct information?
- What am I unsure of and what might I be missing?
- Does the person I disagree with have more information than me?
Download the poster for this principle
