Skip to main content

🧼 Coding Standards & Best Practices

As we scale from a solo codebase to a collaborative team environment, these best practices aim to strike a balance between speed and structure—so we can move forward briskly but cleanly.

This document outlines our formatting conventions, branching strategies, and general architectural hygiene that help us build sustainably without slowing down iteration velocity.

✍️ Formatting & Structure​

We don’t enforce every linting rule under the sun, but we do value readability and consistency.

General Conventions​

  • Use camelCase for variables and functions.
  • Use PascalCase for component and class names.
  • Avoid unnecessary abbreviations unless they’re ubiquitous (ctx, env, req).
  • Prefer early returns to deeply nested conditionals.
  • Favor pure functions for stateless logic, and clear boundaries for stateful logic (React, Unity, etc.).
  • Use function expressions over declarations for clarity (const doThing = () => {}).
  • Co-locate related files: scripts, styles, and tests live near the component or feature they support.

Comments​

  • Write comments for why, not what.
  • Prefix TODOs with // TODO(username):
  • Avoid commented-out code; if it's not being used, delete it (we have Git).

Logging​

  • Use structured logs (console.log({ msg, value })), not spaghetti debug lines.
  • Strip verbose logs before pushing unless they serve a purpose (flag with DEBUG: if necessary).

🌿 Git Branching Strategy​

Branch names help communicate purpose and context. Our convention is:

# Feature work
feature/add-new-thing

# Bug fixes
bug/fix-overlap-on-mobile

# Ticket-driven work
ticket/001-implement-login-flow

Rules of the Road​

  • Always branch off main unless otherwise specified.
  • Use descriptive names, not fix-thing or stuff.
  • Keep PRs focused: 1 PR = 1 thing.
  • Squash commits for clarity before merging.
  • Reference issues or linear tickets in PR descriptions (Fixes #12 or Linear: PROJ-101).

🧱 Code Organization​

In React / Frontend​

  • Group by feature, not type. 
    src/
      features/
        gallery/
          Gallery.tsx
          Gallery.css
          useGallery.ts
          types.ts
  • Shared components/utilities go under shared/, ui/, or common/.

In Unity / C#​

  • Group ScriptableObjects, Monobehaviours, and editor tools under domain-based folders.
  • Use folders like BuildItems/, Systems/, Runtime/, Editor/ for clarity.
  • Place visual tools (like GraphView editors) under Tools/ and keep UI vs logic clearly separated.

🧪 Tests (Where Applicable)​

  • Unit tests go near the module they test.
  • Favor integration tests for complex systems (e.g. placement validation in Unity).
  • Use mock data factories for repeatable, predictable test cases.
  • Snapshot tests okay for UI components—but only if they fail meaningfully.

🚧 Technical Debt Philosophy​

We don’t chase perfection, but we do avoid messes.

  • Leave things better than you found them.
  • Mark shortcuts with clear comments like // HACK: or // TEMP: with your name/date.
  • Revisit flagged debt in your next touchpoint or backlog it properly.

🧭 Naming & Refactors​

  • Be explicit, not clever.
    • calculatePlacementBounds() > doCalc()
  • Use consistent suffixes:
    • Manager, Controller, Service, Store, Modal—define and stick to them.
  • When refactoring:
    • Rename comprehensively, including references and tests.
    • Commit rename separately if large (git mv over delete/recreate).

🧼 When in Doubt...​

  • Optimize for clarity.
  • Write like someone else will read your code tomorrow (because they will).
  • If it feels messy, flag it and move on with a comment. Don't let perfect block progress.

Last updated: June 6th 2025