The short answer
If a standard can be checked by a tool, it should be, and it should run before review. If it cannot, it needs writing down. Review time is expensive and should be spent on whether the approach is right, not on formatting.
The symptom of getting this wrong is the same feedback appearing in review after review. That is not a developer problem, it is a missing rule.
Automate first
- Formatting, enforced on commit so nobody discusses it
- Linting, with the rules agreed once and applied to everyone
- Type checking where the language supports it
- Tests, running on every pull request
- Dependency and vulnerability scanning
- Build and deployment checks
Everything on that list is a category of review comment that stops happening. The setup cost is small and it is paid back within weeks on any team, augmented or not.
Write down what cannot be automated
| Convention | Why it needs stating |
|---|---|
| How errors are handled and surfaced | Every codebase differs |
| What gets logged, and at what level | Invisible until an incident |
| How configuration is managed | Easy to do three ways |
| Where business logic lives | Architecture drifts without it |
| What needs a test and what does not | Otherwise argued per review |
| How database changes are made | High cost when wrong |
A page covering these takes an afternoon and removes most recurring review comments. It also makes your own onboarding faster, which is the part teams underestimate.
What review is for
Once the mechanical checks pass and the conventions are written, review can do the thing only a person can: is this the right approach, does it fit the system, does it handle the cases the author did not think of, will it be understandable in a year.
That is a better use of an experienced engineer's time than pointing out an indentation, and it is considerably more useful to the person receiving it.
Definition of done
- Code written and self-reviewed.
- Automated checks passing.
- Tests covering the new behaviour and the obvious failure cases.
- Documentation updated where behaviour changed.
- Reviewed and approved by someone who knows the area.
- Deployed to staging and actually exercised.
Agree this before the engagement rather than discovering the gap when something is declared finished and is not.
Hold the standard evenly
Applying stricter standards to external developers than to your own team is both unfair and counterproductive. It creates resentment and it tells you nothing, because the comparison is not like for like.
If a standard is worth enforcing, enforce it on everyone. If it is not worth enforcing on your own team, it is not a standard.