- Unnecessary abstractions - I have seen this happen when companies try to customise a standard product like Kubernetes to make the configuration easier to work with. However, what ends up happening is them defining their own standard or DSL but not keeping docs up-to-date. This makes it hard for new joiners as they have to learn this bespoke standard. If they had not added an abstraction, people who had already worked with the product would be able to jump straight into using it.
- Definition of done
- PR bot
API
- add valuable info to each request context/logger, helps debugging
- set body limit
- request validation
- request logger
- request id
- compile with version
- use plural for arrays
Code Quality
- do not use down database migrations — state no longer matches version control
- use CI/CD to maintain code quality
- keep PRs small and focused — easier to review, less risk
- write tests for behaviour, not implementation details
- delete dead code — version control remembers it
- avoid premature optimisation — measure first
Code Review
- review for correctness, readability, and maintainability
- automate style checks with linters — don’t argue about formatting in reviews
- the reviewer should understand the change, not just approve it
Error Handling
- fail fast — surface errors early rather than hiding them
- use structured logging with context (request ID, user, operation)
- distinguish between recoverable and unrecoverable errors
- don’t swallow errors silently
Documentation
- document the why, not the what — code already shows the what
- keep READMEs up-to-date with setup instructions
- use Architectural Decision Records for significant decisions