coding-reference

Coding Reference

Quick-reference guide for coding standards and backend patterns. Use this as a checklist and reference during development and code review.

---

Part 1: Coding Standards

File Organization

Directory Structure Principles

• Group by feature/domain, not by type
• Keep related files close together
• Limit directory depth (prefer flat over deep)
• Use consistent naming for common directories

File Naming

• Use lowercase with separators (kebab-case or snake_case)
• Be descriptive but concise
• Include type suffix when helpful (e.g., .test.ts, .config.ts)
• Avoid special characters except - and _

File Size

• Prefer smaller, focused files
• Split when file exceeds ~300-500 lines
• Extract reusable components into shared modules

Naming Conventions

General Principles

• Names should reveal intent
• Avoid abbreviations (except well-known ones like id, url, config)
• Be consistent within the project
• Avoid encodings (Hungarian notation, etc.)

TypeScript/JavaScript Patterns

Element	Pattern	Examples
Variables	camelCase descriptive nouns	userCount, isEnabled
Functions	camelCase verb + noun	getUserById, validateInput
Classes	PascalCase noun phrases	ProxyManager, ToolRegistry
Interfaces	PascalCase (no I prefix)	ServerConfig, ToolDefinition
Constants	UPPER_SNAKE_CASE	MAX_RETRIES, DEFAULT_TIMEOUT
Booleans	is/has/can prefix	isValid, hasPermission, canEdit
Enums	PascalCase	ConnectionState, LogLevel

Error Handling

Principles

• Fail fast and explicitly
• Provide actionable error messages
• Log errors with context
• Never swallow exceptions silently

Error Message Format

What happened: <description>
Why it happened: <cause if known>
What to do: <suggested action>

Exception Handling

• Catch specific exceptions, not generic Error
• Re-throw with context when wrapping
• Use custom error classes for domain errors
• Log at appropriate level (error vs. warn)