When I think of code-quality I mostly think of maintainability. Is the code simple and understandable? Does it compartmentalize well? Could a new engineer join the project and be productive on day one?
I've made day-1 productivity a goal for every team project I've been on and found I can usually achieve at least day-2 productivity. One day of set up and opening PR's by day two, assuming the engineer is already familiar with 80% of the technologies used (so not junior).
Ideally an engineer can compile the project, run locally, and open a PR in <8 hours with 0 synchronous meetings.
Things that help a lot even for small projects:
- a README with step by step instructions to compile the project
- START HERE document with a checklist of things to be done, services to join or set up
- Devops that remove the need for knowledge wherever possible. CI/CD, continuous automatic deployments.
- Enforce style with an automatic linter
- Code that is simple, even naïve. Complicated code should be black-boxed or reduced to simple pieces.
- Comments that explain why or refer to useful documentation.
- Local dev environment that mimics but does not affect production.
- Using a library to create database migrations.
Things that help a bit (more and more as the team grows):
- Use a typed language
- Loom explainer videos
- Unit tests
- E2E tests
- style guidelines/templates for PR requests.
- over-documenting. Making sure slack conversations, Notion docs, kanban tickets, and PR's link to each other as much as possible so that you can reverse-engineer your own thought process (or that of another engineer) quickly.
- Keeping a queue ready to go of small tasks appropriate for an engineer brand new to the team.
- staging environment separate from production for experimentation.
Most important:
- Every time a new engineer onboards have them update the README and onboarding docs as they go. Have them post in Slack each thing they get stuck on and how they got unstuck. This way the onboarding process becomes more robust over time.
