engineering-standards

Engineering Standards

A universal reference for writing, reviewing, and shipping high-quality code — regardless of language or framework.

---

1. Core Code Quality Principles

Clarity Over Cleverness

• Optimize for readability and maintainability first.
• Use descriptive, unambiguous names for variables, functions, classes, and files. Long names are fine; vague ones are not.
• Avoid abbreviations unless they are universally understood in context (e.g., id, url, err).

DRY — Don't Repeat Yourself

• Extract repeated logic into shared functions, hooks, utilities, or base classes.
• Shared types, contracts, or DTOs belong in centralized modules — never duplicated.

Single Responsibility

• Each function, class, component, or module should have one clear purpose.
• Break complex logic into small, composable, pure functions where possible.
• Minimize public surface area — expose only what consumers need.

Conciseness

• Prefer expressive, idiomatic code over verbose scaffolding.
• Remove dead code, unused imports, and leftover debug statements before committing.

---

2. Types & Contracts

• Always use strict, explicit types. Avoid any / object / untyped unless genuinely unavoidable and justified with a comment.
• Keep shared data contracts (DTOs, API types, schema types) in centralized modules — never inline or duplicated.
• Prefer narrower types over broad ones (e.g., a union of string literals over string where values are known).

---

3. Error Handling

• Handle all expected error cases explicitly. Do not swallow errors silently.
• Return typed/structured errors or throw domain-specific exceptions — avoid generic catch-alls with no context.
• Do not expose internal error details (stack traces, system paths) to end users or external callers.
• Prefer failing loudly in development; degrade gracefully in production.

---

4. Logging & Observability

• Use structured logging (key-value pairs or JSON) wherever possible — avoid plain string concatenation.
• Use the project's existing logging abstraction — don't introduce new loggers.
• Log at appropriate levels: debug for development detail, info for significant state changes, warn for recoverable issues, error for failures.
• Include enough context in log messages to trace behavior without a debugger.

---

5. Performance & Safety

• Avoid N+1 query patterns — batch or preload relational data where needed.
• Avoid unnecessary allocations inside loops or hot paths.
• Never block async/reactive flows with synchronous operations.
• Treat input validation as a first-class concern — validate at system boundaries (API edges, form inputs, file ingestion).
• Handle data integrity explicitly: don't assume upstream data is clean or in the expected shape.

---

6. Security

• Never hardcode credentials, secrets, API keys, or tokens — use environment variables or a secrets manager.
• Sanitize all user-supplied input before using it in queries, shell commands, file paths, or rendered output.
• Guard against path traversal, command injection, and XSS based on the context.
• Err on the side of least privilege: request only the permissions and access scopes actually needed.

---

7. Testability

• Design code for testability: pure functions, clear boundaries, dependency injection over hard-coded dependencies.
• For any non-trivial behavior, propose or write tests alongside the implementation.
• Tests should be independent, deterministic, and fast. Avoid shared mutable state between test cases.
• See references/testing-guidelines.md for naming conventions and test structure.

---

8. Documentation & Comments

• Only add comments that provide context or explain non-obvious reasoning. Do not comment on self-explanatory code.
• Use doc-comment conventions for public APIs (JSDoc, KDoc, docstrings, etc.) — describe parameters, return values, and behavior.
• Avoid redundant comments that restate what the code already says. Focus on why, not what.

Good:

// Retry up to 3 times — downstream service has known transient failures under load

Bad:

// Increment counter by 1
counter++

---

9. Code Review Mode

When asked to review code, a diff, or a PR:

1. Only comment when you have high confidence (>80%) that a real issue exists. If uncertain, don't comment.
2. Be concise — one sentence per comment when possible.
3. Focus on actionable feedback, not observations or style preferences unless they violate a principle above.
4. Do not call submit/publish on reviews. Always leave reviews in pending/draft state for the author to submit.

Priority Areas for Review

Priority	Examples
Security	Hardcoded secrets, missing input validation, command/path injection, error messages leaking internals
Correctness	Logic errors, race conditions, resource leaks, off-by-one errors, incorrect error propagation
Architecture	Violations of existing codebase patterns, missing error handling, blocking in async contexts
Maintainability	Unnecessary duplication, overly defensive code, comments restating obvious behavior

---

10. Git Workflow

Branch Naming

• With a Jira ticket: HMD-1234_short_description_of_change
• Without a Jira ticket: NO_JIRA_short_description_of_change
• Use underscores, lowercase, and keep it concise but descriptive.

Commit Messages

• Format: [TICKET-ID or NO_JIRA] present-tense description of change
• Examples:
  • HMD-2601 add NLD eligibility check before create
  • NO_JIRA fix race condition in session refresh
• Keep the first line under 72 characters. Add a body if the why needs more explanation.

Before Pushing

• Run all relevant tests locally.
• Ensure all CI checks pass, including code coverage requirements.
• Remove debug logging, commented-out code, and TODO comments that shouldn't be shipped.

Pull Request Descriptions

Use this template:

## Description
{Brief description of the changes and motivation}

## Related Jira Tickets
{Full Jira ticket URL, or NO_JIRA}

## Screenshots (if any)
{Add after testing}

• Do not use emojis in PR titles or descriptions.
• Keep the title in the same format as commit messages: TICKET-ID short description.

---

Quick Reference

Concern	Guideline
Naming	Descriptive > short. Long names are fine.
Types	Strict and explicit. No any without justification.
Errors	Handle explicitly. Don't swallow. Don't leak internals.
Comments	Explain why, not what.
Tests	Pure functions + DI = testable. Write tests for non-trivial logic.
Security	Validate inputs at boundaries. No hardcoded secrets. Least privilege.
Commits	TICKET-ID present-tense description
PRs	No emojis. Use the template.

---

For extended testing guidelines, see references/testing-guidelines.md.