Code Review & Git

Keep pull requests small and focused

Limit pull requests to a single feature, fix, or refactor. Small, focused PRs are easier to review, less error-prone, and easier to roll back if necessary.

• Keep PRs under ~300 lines of actual changes when possible

• Avoid mixing unrelated changes (e.g. feature + formatting)

• Split large tasks into smaller incremental PRs

Write descriptive PR titles and summaries

Use meaningful titles and summaries that describe what the PR does, why it's needed, and any important context or edge cases. This helps reviewers and future maintainers understand the intent.

Title:

Fix: Prevent duplicate emails in registration form

Description:

1This PR prevents users from registering with an email that already exists.
2- Adds server-side check
3- Displays validation error in UI
4- Includes unit tests for edge cases

Review code for design, not just style

Go beyond formatting and naming — assess whether the code is clear, reusable, and fits into the overall architecture. Look for broken abstractions, tight coupling, and redundant logic.

• Ask: Is this the right place for this logic?

• Check: Does it follow architectural conventions?

• Suggest: Better patterns if applicable

Leave constructive and respectful review comments

Focus on collaboration, not criticism. Explain why something might be problematic and suggest alternatives. Avoid nitpicking — group style comments together or rely on linters.

Bad Example:

"This is wrong. Rewrite it."

Good Example:

"This function looks a bit long — what do you think about extracting the API call to a helper for clarity?"

Use checklists for reviews and submissions

Create or follow checklists to ensure quality standards are met before merging or reviewing a pull request. This helps prevent missed tests, missing types, or config changes.

Sample Checklist:

• Code builds and tests pass

• Types are correct

• Feature is documented

• No debug code left (console.log, etc.)

Require CI to pass before merge

Always require that linting, testing, and build checks pass in CI before merging. This ensures the main branch stays healthy and deployable.

• Block merging unless CI passes

• Include type checks (e.g. tsc), tests, and linters in CI

• Run tests in parallel for speed

Write clear and conventional commit messages

Use consistent commit message formats to make the project’s history easier to read, automate changelogs, and enable semantic versioning. Follow a structure like:

<type>: <short summary>

Examples:

• feat: add comment moderation UI

• fix(api): handle missing token error

• refactor(db): use transactions for writes

Common types: feat, fix, docs, style, refactor, test, chore

Rebase and squash before merging

Use interactive rebase and squash commits to combine work into meaningful units. Avoid noisy commit history (fix typo, debug, wip) on main branches.

• Squash to one commit per PR when possible

• Keep feature branches clean and linear

• Rebase onto main to avoid merge commits

Follow a clear branching strategy

Adopt a branching strategy like trunk-based development, Git Flow, or GitHub Flow to align how features, releases, and hotfixes are managed.

• main: stable, deployable

• dev: integration branch (optional)

• feature/*, bugfix/*, release/*: purpose-driven branches