Naming Conventions

• camelCase for variables, functions, methods, and parameters
• PascalCase for classes, interfaces, types, and enums
• All code and comments must be in English
• Names must reveal intent: getUserById instead of get, calculateTotalPrice instead of calc
• Boolean variables/methods use prefixes: isActive, hasPermission, canEdit, shouldRetry
• Avoid cryptic abbreviations: transaction instead of tx, configuration instead of cfg
• Collections should be plural: users, orderItems, activeConnections

Documentation

• Every method must have JSDoc comments including:

- Description of what the method does - @param tags with types and descriptions for all parameters - @returns tag with type and description of the return value - @throws tag documenting any exceptions the method may throw

Example:

/**
 * Calculates the total price including tax.
 * @param {number} basePrice - The base price before tax
 * @param {number} taxRate - The tax rate as a decimal (e.g., 0.21 for 21%)
 * @returns {number} The total price including tax
 * @throws {Error} If basePrice or taxRate is negative
 */
function calculateTotalPrice(basePrice: number, taxRate: number): number {
  if (basePrice < 0 || taxRate < 0) {
    throw new Error('Price and tax rate must be non-negative');
  }
  return basePrice * (1 + taxRate);
}

Design Principles

Avoid Over-Abstraction

• Only abstract when there is a clear, demonstrated need
• Prefer concrete implementations over premature generalization
• Wait until you have at least two or three concrete use cases before creating an abstraction

Minimize Long-Term Complexity

• Concentrate internal complexity behind simple, consistent interfaces - The implementation can be complex, but the API should be intuitive
• Create deep abstractions that do much with little - Prefer modules that provide significant functionality through a minimal interface
• Avoid premature generalizations - Solve the problem at hand; don't design for hypothetical future requirements
• Use comments only to explain decisions and reasoning that the code cannot express - Comments should answer "why", not "what"

Interface Design

• Keep public interfaces small and focused
• Hide implementation details aggressively
• Make common operations simple and rare operations possible
• Prefer composition over inheritance when the relationship is not strictly "is-a"

Immutability by Default

• Prefer const over let whenever possible
• Use readonly for properties that should not be mutated after initialization
• Prefer immutable array methods (.map(), .filter(), .reduce()) over mutations (.push(), .splice())
• When state must change, create new objects/arrays instead of mutating existing ones

Strict Typing

• Never use any — use unknown when the type is truly unknown, then narrow it
• Enable strict: true in tsconfig.json
• Prefer specific types over broad generic types
• Use union types and type guards for runtime type safety
• Define explicit return types for public methods

Testing

• Every public method must have corresponding unit tests
• Tests should cover:

- Happy path (expected behavior with valid inputs) - Edge cases (empty arrays, null values, boundary conditions) - Error cases (invalid inputs, expected exceptions)

• Test names should describe the expected behavior: should return null when user is not found
• Keep tests independent — each test should set up its own data and not depend on other tests
• Aim for tests that are fast, isolated, and deterministic

Dependencies

• Always verify the latest version before installing any package
• Check npm or the official documentation to ensure you are installing the most recent stable version
• Use npm info <package> version or check npmjs.com to confirm the latest version
• Avoid installing outdated packages that may have known vulnerabilities or missing features