coding-standards

Coding Standards Skill

Enforced code quality standards and patterns for production TypeScript/JavaScript projects.

When to Use

This skill is always relevant when writing or reviewing code. It defines the non-negotiable quality baseline.

---

1. Core Principles

Immutability — NEVER Mutate

// ❌ MUTATION — causes hidden bugs, breaks React rendering, ruins debugging
const users = [{ id: 1, name: 'Alice' }]
users.push({ id: 2, name: 'Bob' })         // mutates array
users[0].name = 'Alicia'                     // mutates object

// ✅ IMMUTABLE — predictable, traceable, safe
const added = [...users, { id: 2, name: 'Bob' }]
const updated = users.map(u => u.id === 1 ? { ...u, name: 'Alicia' } : u)
const removed = users.filter(u => u.id !== 1)

// For deep updates, use structured spread or immer:
const deepUpdate = {
  ...state,
  user: {
    ...state.user,
    address: { ...state.user.address, city: 'New York' }
  }
}

Single Responsibility — One Reason to Change

// ❌ GOD FUNCTION: validates, transforms, persists, notifies
async function handleUserRegistration(req: Request) {
  // 80+ lines doing everything...
}

// ✅ DECOMPOSED: each function does one thing
async function handleUserRegistration(req: Request) {
  const input = validateRegistrationInput(req.body)  // validate
  const user = await createUser(input)                // persist
  await sendWelcomeEmail(user.email)                  // notify
  return formatUserResponse(user)                     // transform
}

---

2. Naming Conventions

Variables and Functions

// Boolean: use is/has/can/should prefix — reads like English
const isActive = true
const hasPermission = user.role === 'admin'
const canEdit = hasPermission && !isLocked
const shouldRetry = attempts < MAX_RETRIES

// Functions: verb + noun — describes the action
function getUserById(id: string): Promise<User> {}
function calculateOrderTotal(items: OrderItem[]): number {}
function formatCurrency(amount: number, locale: string): string {}

// Event handlers: handle + Event
function handleSubmit(event: FormEvent) {}
function handleUserCreated(user: User) {}

// Avoid: vague names, abbreviations, single letters (except loops)
// ❌ data, info, temp, val, res, cb, fn, idx
// ✅ userData, connectionInfo, temporaryToken, responseBody