Coding Standards & Best Practices

Non-negotiable rules

Apply non-negotiable rules (19 rules, ordered by impact) before anything else.

Agent Instructions

After reading this skill:

Apply ALL rules to every file you create or modify
Run the Pre-output Validation checklist before returning any code
If a rule conflicts with a user request, flag it explicitly and propose a compliant alternative
Reference specific rule names when explaining choices (e.g., "Per the KISS principle, I simplified this by...")
Load example files on demand — only read the relevant file for the task at hand

Code Quality Principles

Principle	Rule
Readability First	Code is read more than written. Clear names > clever code.
KISS	Simplest solution that works. Avoid over-engineering.
Avoid GodComponent	Single responsibility per component; extract utilities, hooks, sub-components.
DRY	Extract common logic. Create reusable components.
YAGNI	Don't build features before they're needed.
Immutability	Never mutate — always return new values.

Avoiding GodComponent (decomposition strategy)

Apply the following order to keep components focused and testable:

Extract pure TypeScript utilities first
- Move logic that has no React dependency into pure functions.
- If a utility takes more than one argument, use object destructuring in the signature so argument names are explicit at the call site. Extract the parameter type (e.g.
```
interface FormatRangeArgs { start: number; end: number }
```
  then
```
const formatRange = ({ start, end }: FormatRangeArgs) => ...
```
  ).
- Reusable across features → put in
```
src/utils/xyz.utils.ts
```
  .
- Feature-specific → keep next to the component as
```
component-name.utils.ts
```
  (same kebab-case base name as the component file, e.g.
```
market-list-item.utils.ts
```
  next to
```
market-list-item.tsx
```
  ).
Extract logic into named hooks
- Move state, effects, and derived logic into hooks (e.g.
```
use-xyz.ts
```
  ).
- Reusable across features → put in
```
src/hooks/use-xyz.ts
```
  .
- Feature-specific → keep in the feature’s
```
hooks/
```
  subdirectory (e.g.
```
features/market-list/hooks/use-market-filters.ts
```
  ).
Split the visual layer into sub-components
- If the render/JSX exceeds roughly 40 lines, extract sub-components with clear props and a single responsibility.
- Each sub-component should have its own props interface and live in its own file (or a dedicated subfolder) when it grows.

Sections & Example Files

TypeScript / JavaScript

Topic	Example File	When to load
Variable & function naming (incl. boolean prefixes)	`examples/typescript/naming.ts`	When naming anything (arrow functions only; booleans: is/has/should/can/will)
Immutability patterns	`examples/typescript/immutability.ts`	When working with state/objects/arrays
Error handling	`examples/typescript/error-handling.ts`	When writing async code
Async / Promise patterns	`examples/typescript/async-patterns.ts`	When using await/Promise
Type safety	`examples/typescript/type-safety.ts`	When defining interfaces/types (no inline types; no nested types; extract named types)
Control flow & readability	`examples/typescript/control-flow.ts`	Early returns, const vs let, Array.includes/some, nullish coalescing, destructuring

React

Topic	Example File	When to load
Component structure	`examples/react/component-structure.tsx`	When creating a component

Testing

Topic	Example File	When to load
Unit test patterns	`examples/testing/unit-testing-patterns.tsx`	When writing Jest/RTL tests (AAA, screen, spyOn, it.each, getByRole, mock factory)

Anti-patterns (read during code review)

Topic	File
All BAD patterns grouped	`anti-patterns/what-not-to-do.ts`
Code smells detection	`anti-patterns/code-smells.ts`

File Organization Rules

200–400 lines typical file length
800 lines absolute maximum
One responsibility per file (high cohesion, low coupling)
File names: always kebab-case (lowercase with hyphens). No PascalCase or camelCase in file or folder names.

components/button.tsx           # kebab-case (not Button.tsx)
hooks/use-auth.ts               # kebab-case (not useAuth.ts)
lib/format-date.ts              # kebab-case (not formatDate.ts)
types/market.types.ts           # kebab-case + optional .types / .utils / .store suffix
features/market-list/market-list-item.tsx
settings-screen.tsx              # e.g. settings-screen.tsx, use-device-discovery.ts

Components and hooks are still exported with PascalCase (components) or camelCase with

use

prefix (hooks); only the file name is kebab-case.

Code Style / TypeScript

TypeScript strict mode — enable in
```
tsconfig.json
```
for maximum type safety.
Explicit function signatures — type function parameters and return types explicitly; avoid relying on inference for public APIs.
Type inference for locals — prefer inference for local variables when the type is obvious (e.g.
```
const count = 0
```
).

React Components

FunctionComponent — type React components with
```
FunctionComponent<Props>
```
(or
```
FC<Props>
```
); use typed props interfaces, not inline or
```
any
```
.
Early returns — use early returns in component bodies to keep the main render path flat and readable.
Fragment shorthand — use
```
<>...</>
```
instead of
```
<Fragment>
```
unless a
```
key
```
is required.
Exports — prefer named exports for components; default export only when required by the framework (e.g. Expo Router).

React Hooks

Functions vs hooks — prefer a plain function to a custom hook when you don't need React primitives (state, effects, context).
use prefix — use the
```
use
```
prefix only for real hooks; never for plain functions.
useMemo / useCallback — avoid for simple computations or callbacks; use when profiling shows a need or when passing callbacks to memoized children.
Handlers — use a single arrow function per handler (e.g.
```
const handleClick = () => { ... }
```
); avoid function factories that return handlers.
Selected items — store selection by ID in state and derive the full item from the list (e.g.
```
selectedItem = items.find(i => i.id === selectedId)
```
); avoids stale references when the list updates.

Data fetching (async: loading, error, data)

Prefer TanStack Query — for any async call that involves
```
isLoading
```
, error handling, and result data, use
```
useQuery
```
(or
```
useMutation
```
for writes) instead of manual
```
useState
```
+
```
useEffect
```
. You get caching, deduplication, and consistent loading/error state for free.
Query key factory — define a single source of truth for cache keys (e.g.
```
XxxQueryKey.all
```
,
```
XxxQueryKey.list(...)
```
,
```
XxxQueryKey.detail(id)
```
). See references/query-keys-example.ts and assets/hook-tanstack-query-template.ts.

Error Handling

Context in messages — include a prefix in error and log messages (e.g.
```
[ComponentName] failed to load
```
).
Rethrow policy — rethrow only when adding context or transforming the error type; don't rethrow after logging unless the caller needs to handle the failure.

Architecture & Organisation

Feature structure — each feature should be self-contained: its own components,
```
hooks/
```
subdirectory,
```
*.utils.ts
```
and
```
*.types.ts
```
files, and Controllers/Services for complex business logic (e.g.
```
features/scene-3d/
```
,
```
scene-manager/controllers/
```
).
Single responsibility — one clear responsibility per file; keep components small and focused. Apply the Avoiding GodComponent (decomposition strategy): utilities first, then hooks, then sub-components when the visual layer exceeds ~40 lines.
Composition over inheritance — prefer composing small components and utilities over class inheritance.
Group related code — keep related functionality together (e.g. by feature or domain).

Comments

Self-documenting first — prefer clear names and structure over comments; comment only when behavior is non-obvious.
Explain "why" not "what" — comments should explain rationale, side effects, or workarounds, not restate the code.
Keep comments up to date — remove or update comments when code changes.
TODO with ticket ID — use a traceable format for TODOs (e.g.
```
// TODO: JIRA-1234 - description
```
).

Logging

Logger with levels — use a logger (e.g.
```
logger.info()
```
,
```
logger.error()
```
,
```
logger.warn()
```
,
```
logger.debug()
```
) instead of
```
console.*
```
in client code.
Context prefix — include a context prefix in log messages (e.g.
```
[useDeviceDiscovery] storing last known camera IP
```
).
Server exception —
```
console.log
```
is acceptable in server-side or API route code for debugging.

Function Parameters

Destructuring for multiple params — use object destructuring when a function has more than one parameter (e.g.
```
const fn = ({ a, b }: Args) => ...
```
).
Extract parameter types — export parameter types as named types/interfaces instead of inline typing.
Optional parameters — use
```
param?: Type
```
rather than
```
param: Type | undefined
```
.
Defaults in destructuring — set default values in the destructuring when possible (e.g.
```
{ page = 1, size = 10 }
```
).

TypeScript Best Practices

ReactNode for children — use
```
ReactNode
```
for component children (not
```
JSX.Element | null | undefined
```
).
PropsWithChildren — use
```
PropsWithChildren<Props>
```
for components that accept
```
children
```
.
Record<K, V>
— prefer the
```
Record<K, V>
```
utility type over custom index signatures.
Array.includes() — use for multiple value checks instead of repeated
```
===
```
comparisons.
Array.some() — use for existence checks instead of
```
array.find(...) !== undefined
```
.
Explicit enum values — use explicit numeric (or string) values for enums so they survive reordering and serialization.

React Native (when applicable)

When working in a React Native or Expo project:

Spacing — prefer
```
gap
```
,
```
rowGap
```
, and
```
columnGap
```
over
```
margin
```
/
```
padding
```
for spacing between elements.
Responsive layout — use
```
useWindowDimensions
```
instead of
```
Dimensions.get
```
for layout that reacts to size changes.
Static data outside components — move constants and pure functions that don't depend on props or state outside the component to avoid new references on every render.

Pre-output validation

Before returning any code, run the Pre-output Validation checklist.

Templates

Skeletons to copy and adapt (file names in kebab-case):

Type	File	Use when
Hook	assets/hook-template.ts	Creating a data-fetching or effect hook
Hook (TanStack Query)	assets/hook-tanstack-query-template.ts	Creating a hook with @tanstack/react-query (queryKey, queryFn, placeholderData)
Component	assets/component-template.tsx	Creating a React component
Utility	assets/utils-template.ts	Creating pure or side-effect helpers ( `*.utils.ts` )

Validation

Validate this skill's frontmatter and structure with skills-ref:

bash

skills-ref validate ./skills/typescript-and-react-guidelines

typescript-and-react-guidelines

NPX Install

Tags

SKILL.md Content