Skip to content

engineering-standards.md

Latest commit

 

History

History
92 lines (61 loc) · 5.06 KB

engineering-standards.md

File metadata and controls

92 lines (61 loc) · 5.06 KB

Engineering Standards

These are the standards every engineer at Zap Tech follows. They're not guidelines or suggestions. They're how we work.

Code Review

Every line of code that reaches production goes through review. No exceptions, regardless of seniority.

What we look for:

  • Correctness — does it actually solve the problem? Does it handle edge cases?
  • Clarity — can another engineer understand this without a walkthrough? If you need a comment to explain what the code does, the code should probably be rewritten.
  • Simplicity — is this more complex than it needs to be? Three similar lines of code is better than a premature abstraction.
  • Security — any injection risks? Unvalidated input? Exposed credentials? Auth checks in place?
  • Performance — any obvious bottlenecks? N+1 queries? Unnecessary allocations?
  • Tests — does the PR include tests for new behavior? Do existing tests still pass?

What we don't do:

  • Nitpick formatting. That's what linters are for.
  • Block PRs over style preferences that don't affect correctness or readability.
  • Let PRs sit for days without review. If you're tagged, you review within 24 hours.

Review is a conversation, not a gatekeeping exercise. The goal is better code, not proving who's smarter.

Pull Requests

A good PR is small, focused, and self-explanatory.

  • One concern per PR. A bug fix and a feature don't belong in the same PR. A refactor and a behavior change don't belong in the same PR.
  • Descriptive titles. The title should tell the reviewer what changed without opening the PR. "Fix race condition in payment webhook handler" is good. "Fix bug" is not.
  • Context in the description. Why was this change needed? What approach did you take and why? Are there any tradeoffs? Link to the issue if there is one.
  • Small diffs. If a PR is over 400 lines, it probably should have been split. Large PRs get worse reviews because reviewers lose focus.
  • Tests included. If you're changing behavior, the tests prove it works. If you're fixing a bug, the test reproduces the bug and verifies the fix.

What "Done" Means

A feature is done when:

  1. The code is written, reviewed, and merged.
  2. Tests pass in CI.
  3. It's deployed to staging and verified.
  4. The client can see and test it.
  5. Any necessary documentation is updated.

"Done" is not "it works on my machine." "Done" is not "the code is merged but I haven't tested it." "Done" means a user can use it and it works correctly.

Documentation

We don't write documentation for its own sake. We write it when it prevents someone from wasting time.

What gets documented:

  • Architecture decisions. When we choose technology A over technology B, we write down why. Six months from now, nobody will remember the reasoning unless it's written down.
  • System boundaries. How services communicate, what the data flow looks like, where the external dependencies are.
  • Setup instructions. A new engineer should be able to clone the repo and have a working development environment in under 30 minutes. If it takes longer, the setup docs are broken.
  • API contracts. Request/response formats, authentication requirements, error codes. Generated from code (OpenAPI) whenever possible.
  • Runbooks. How to deploy, how to roll back, how to access logs, how to respond to common incidents.

What doesn't get documented:

  • Code that explains itself. If the function is called calculate_total_with_tax and the implementation is straightforward, a docstring adds nothing.
  • Obvious process. We don't need a document that says "create a branch, open a PR, get it reviewed."

Technical Debt

Every project accumulates technical debt. The question is whether you manage it or ignore it until it buries you.

Our approach:

  • Track it. Technical debt gets filed as issues, labeled, and prioritized alongside feature work. It's not a secret list in someone's head.
  • Budget for it. We allocate time in every project for debt reduction. The exact amount depends on the project's maturity and the client's priorities — but it's never zero.
  • Be honest about it. When we take a shortcut to hit a deadline, we document it and create the ticket to fix it later. The shortcut is a conscious decision, not an accident.
  • Don't gold-plate. Paying down debt doesn't mean rewriting everything. Fix the things that slow you down or cause bugs. Leave the rest alone.

The worst technical debt is the kind nobody knows about. We make it visible so decisions about it are intentional.

Linting and Formatting

Automated. Non-negotiable. Runs in CI.

Rust:

  • cargo fmt — formatting is not a discussion
  • cargo clippy — catches common mistakes and non-idiomatic patterns
  • cargo audit — checks dependencies for known vulnerabilities

TypeScript:

  • ESLint with strict config
  • Prettier for formatting
  • tsc --noEmit for type checking

If the linter disagrees with you, fix your code. If the linter is genuinely wrong, change the rule in the config and document why. Don't add // eslint-disable or #[allow] without a comment explaining the exception.