Coding Standards & Best Practices

Name: coding-standards
Rating: 92
Author: Lichens-Innovation

⚠️ NON-NEGOTIABLE RULES (apply before anything else)

•NEVER mutate objects or arrays — always use spread operator
•NEVER use any type in TypeScript — define proper interfaces
•ALWAYS use arrow functions — never the function keyword for top-level or module-level functions (const fn = () => {})
•ALWAYS handle errors in async functions with try/catch
•Functions MUST stay under 50 lines — split if needed
•Files MUST stay under 800 lines — split if needed
•NO magic numbers — extract as named constants
•NO deep nesting (max 4 levels) — use early returns
•Prefer ?? over || for null/undefined — use nullish coalescing (??) so that 0, "", and false are not treated as missing
•NO inline types — extract types/interfaces to named declarations (DRY, reuse, single source of truth)

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.
DRY	Extract common logic. Create reusable components.
YAGNI	Don't build features before they're needed.
Immutability	Never mutate — always return new values.

Sections & Example Files

TypeScript / JavaScript

Topic	Example File	When to load
Variable & function naming	`examples/typescript/naming.ts`	When naming anything (arrow functions only)
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)

React

Topic	Example File	When to load
Component structure	`examples/react/component-structure.tsx`	When creating a component
Custom hooks	`examples/react/custom-hooks.tsx`	When extracting reusable logic
State management	`examples/react/state-management.tsx`	When using useState/useReducer

API Design

Topic	Example File	When to load
Response format	`examples/api/response-format.ts`	When writing API handlers
Input validation	`examples/api/input-validation.ts`	When validating request bodies

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)

code

components/Button.tsx          # PascalCase for components
hooks/useAuth.ts               # camelCase with 'use' prefix
lib/formatDate.ts              # camelCase for utilities
types/market.types.ts          # camelCase with .types suffix

Pre-output Validation (MANDATORY)

Before returning any code, verify each point:

• Every function is under 50 lines → if not, split it
• No any types → replace with proper interfaces
• No inline types → extract to named types/interfaces (DRY, reuse)
• All async functions have try/catch → add if missing
• No direct mutations → convert to spread pattern
• No magic numbers → extract as named constants
• No deep nesting (>4 levels) → refactor with early returns
• No console.log left in production code
• File stays under 800 lines → split if needed