code-conventions

Code Conventions

This skill contains project-wide coding standards. Agents load this when writing or reviewing code. Do not duplicate these rules in agent prompts.

Each rule is paired with a concrete example. Reviewers cite the rule name (e.g. "BLOCKER: code-conventions #magic-number") so the author can find the rule and the example without context-switching.

General

• #explicit-over-clever — Code is read more than it is written.

  // BAD: clever — what does the !! do? what's the precedence?
  const isReady = !!user && !!user.config && !!user.config.ready;
  // GOOD: explicit — reads top-to-bottom.
  const isReady = user != null && user.config != null && user.config.ready === true;
  

• #docstring — Every exported function has a docstring/JSDoc.

• #magic-number — Use a named constant when a literal would otherwise be unexplained.

  // BAD: what is 86400000?
  setTimeout(reload, 86400000);
  // GOOD:
  const MS_PER_DAY = 24 * 60 * 60 * 1000;
  setTimeout(reload, MS_PER_DAY);
  

• #no-commented-code — No commented-out code in commits. Use git history if you need to remember what was there.

Naming

Layer	Convention	Example
Files	kebab-case (all languages)	user-store.ts, user_store.py, UserStore.kt is wrong
Classes / Types	PascalCase	UserStore, OrderId
Functions / variables	camelCase	getUser, orderCount
Constants	SCREAMING_SNAKE_CASE	MAX_RETRIES, JWT_SECRET
Database columns	snake_case	user_id, created_at

Error Handling

• #no-silent-swallow — Never swallow an error without a comment explaining why.

  // BAD: error vanishes — why?
  try { await unlink(tmp); } catch {}
  // GOOD: intent stated; reviewer can verify it.
  try { await unlink(tmp); } catch { /* tmp already gone — best-effort cleanup */ }
  

• #typed-errors — Don't throw bare strings; throw Error (or a subclass).

  // BAD: caller can't .message or .stack on a string.
  if (!user) throw "user not found";
  // GOOD:
  if (!user) throw new NotFoundError(`user ${id} not found`);