Craft
Code Quality
We write code that the next person can read, understand, and change without fear. That is the standard.
Reviews
Pull Request Reviews
Every pull request gets reviewed. No exceptions. Not even "it is just a one-line fix." Especially not "it is just a one-line fix." Those are the ones that break production.
What a real review looks like:
- Read every line of the diff. Not just the files that changed, but the context around them.
- Check that tests exist and test the right things. "It does not crash" is not a test.
- Ask questions when something is unclear. "Why did you choose X over Y?" is a good review comment.
- Push back when something is wrong. Do not approve to be polite.
What a review is NOT:
- Scanning the diff for 10 seconds and clicking Approve.
- Only checking for syntax errors.
- Waiting 3 days to review because you are busy.
Review turnaround matters. If someone is waiting on your review, they are blocked. Unblock them within 24 hours.
Testing
Write Tests
Every feature has tests. Not because someone told you to. Because code without tests is code you cannot change with confidence.
Write the test that would have caught the bug you just fixed. Write the test that proves the feature works as described. Write the test that checks the edge case you almost missed.
We do not have a strict TDD policy. Write tests before or after, we do not care. But the PR does not get approved without them.
Commits
Commit Messages
A commit message answers two questions: what changed, and why.
Bad
fix bug
update stuff
wip
Good
Fix N+1 query on users index causing 2s page loads
Add rate limiting to API endpoints (max 100 req/min)
Your commit history is documentation. Six months from now, someone (probably you) will need to understand why a change was made. Make their life easier.
Principles
Code Principles
- Leave code better than you found it. Every PR is an opportunity to clean up something nearby.
- Name things for what they do, not how they work.
calculate_invoice_totalbeatssum_line_items_with_tax_and_discount. - Delete code you are not using. Commented-out code is not "keeping our options open." It is clutter.
- Keep dependencies updated. A monthly dependency update is maintenance. A yearly one is a migration.
- When in doubt, choose the boring solution. Clever code is fun to write and miserable to debug.