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_total beats sum_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.