coding-standards

Coding Standards

This is the language-agnostic layer: decision heuristics that apply whether the file is Go, TypeScript, or PHP. For a specific language or framework's idioms, use the dedicated skill instead — skills/go-service-idioms/, skills/api-design/, skills/laravel-patterns/, skills/vue-nuxt-frontend-patterns/. This skill only covers what's genuinely cross-cutting: it skips KISS/DRY/YAGNI definitions and other things any competent reviewer already knows, and focuses on the concrete thresholds and rationalizations that actually distinguish a maintainable change from one that technically works.

When to use

Reviewing code for maintainability across languages; setting up lint rules; establishing conventions a mixed-language team will actually follow without a language-specific skill to lean on.

Function size and nesting

A function whose body exceeds ~50 lines is usually doing more than one thing — the fix is extracting named sub-steps, not shrinking whitespace:

// One function, three responsibilities hidden inside it
function processMarketData() { /* validate, transform, persist, ~100 lines */ }

// Three named steps, each independently testable
function processMarketData() {
  const validated = validateData()
  const transformed = transformData(validated)
  return saveData(transformed)
}

Nesting past 3-4 levels is a comparable signal. Guard clauses (early returns) collapse a pyramid of conditions into a flat list of exits, which is easier to scan and to add a fifth condition to later:

// 5 levels deep
if (user) { if (user.isAdmin) { if (market) { if (market.isActive) { if (hasPermission) { /* ... */ } } } } }

// Flat
if (!user) return
if (!user.isAdmin) return
if (!market) return
if (!market.isActive) return
if (!hasPermission) return
// ...

Magic numbers and strings

An unexplained literal in a conditional or a timeout is a landmine for the next reader, who has to guess whether 3 and 500 are related, arbitrary, or load-bearing: