클린 코드 실전 원칙 2025: 읽기 좋은 코드를 작성하는 30가지 규칙

// 무엇을 의미하는지 전혀 알 수 없다
const d: number = 86400;
const list1: number[] = [1, 2, 3];

function calc(a: number, b: number): number {
  return a * b * 0.1;
}

// 이름만 봐도 의미가 명확하다
const SECONDS_PER_DAY: number = 86400;
const activeUserIds: number[] = [1, 2, 3];

function calculateDiscountedPrice(originalPrice: number, quantity: number): number {
  const DISCOUNT_RATE = 0.1;
  return originalPrice * quantity * DISCOUNT_RATE;
}

# Bad
d = 86400
lst = [1, 2, 3]

def calc(a, b):
    return a * b * 0.1

# Good
SECONDS_PER_DAY = 86400
active_user_ids = [1, 2, 3]

def calculate_discounted_price(original_price: float, quantity: int) -> float:
    DISCOUNT_RATE = 0.1
    return original_price * quantity * DISCOUNT_RATE

const usrMgr = new UserManager();
const btnClkHndlr = () => {};
const genRpt = (dt: Date) => {};
const tmpUsr = getUser();

const userManager = new UserManager();
const handleButtonClick = () => {};
const generateReport = (reportDate: Date) => {};
const temporaryUser = getUser();  // 맥락상 임시 변수라면 이조차도 재고

// 5가 무엇을 의미하는가? 프로젝트에서 '5'를 검색하면 수백 개 결과가 나온다
if (user.role === 5) {
  setTimeout(callback, 86400000);
}

const ADMIN_ROLE_ID = 5;
const ONE_DAY_IN_MILLISECONDS = 86400000;

if (user.role === ADMIN_ROLE_ID) {
  setTimeout(callback, ONE_DAY_IN_MILLISECONDS);
}

class DtaRcrd102 {
  private genymdhms: Date;  // "젠와이엠디에이치엠에스"??
  private modymdhms: Date;
  private pszqint: number;
}

class Customer {
  private generationTimestamp: Date;
  private modificationTimestamp: Date;
  private recordId: number;
}

// 같은 개념에 fetch, retrieve, get, obtain을 혼용
class UserService {
  fetchUser(id: number) {}
  retrieveAccount(id: number) {}
  getUserProfile(id: number) {}
  obtainUserSettings(id: number) {}
}

// get으로 통일
class UserService {
  getUser(id: number) {}
  getAccount(id: number) {}
  getUserProfile(id: number) {}
  getUserSettings(id: number) {}
}

// 루프 변수에 긴 이름
for (let arrayIndex = 0; arrayIndex < items.length; arrayIndex++) {
  process(items[arrayIndex]);
}

// 전역 상수에 짧은 이름
const T = 3000;  // 무슨 타임아웃?

// 루프 변수는 짧게
for (let i = 0; i < items.length; i++) {
  process(items[i]);
}

// 전역/모듈 수준은 설명적으로
const API_REQUEST_TIMEOUT_MS = 3000;

function processOrder(order: Order): OrderResult {
  // 검증 (20줄)
  if (!order.items || order.items.length === 0) {
    throw new Error('No items');
  }
  if (!order.customer) {
    throw new Error('No customer');
  }
  // ... 더 많은 검증

  // 가격 계산 (30줄)
  let total = 0;
  for (const item of order.items) {
    total += item.price * item.quantity;
  }
  const tax = total * 0.1;
  const shipping = total > 100 ? 0 : 10;
  // ... 더 많은 계산

  // 결제 처리 (20줄)
  const paymentResult = chargeCard(order.customer.cardId, total + tax + shipping);
  // ... 결제 로직

  // 알림 전송 (15줄)
  sendEmail(order.customer.email, 'Order confirmed');
  // ... 알림 로직

  return { orderId: generateId(), total, status: 'completed' };
}

function processOrder(order: Order): OrderResult {
  validateOrder(order);
  const pricing = calculatePricing(order.items);
  const paymentResult = processPayment(order.customer, pricing.total);
  notifyCustomer(order.customer, paymentResult);

  return createOrderResult(paymentResult, pricing);
}

function validateOrder(order: Order): void {
  if (!order.items?.length) throw new InvalidOrderError('No items');
  if (!order.customer) throw new InvalidOrderError('No customer');
}

function calculatePricing(items: OrderItem[]): Pricing {
  const subtotal = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
  const tax = subtotal * TAX_RATE;
  const shipping = subtotal > FREE_SHIPPING_THRESHOLD ? 0 : SHIPPING_FEE;
  return { subtotal, tax, shipping, total: subtotal + tax + shipping };
}

function emailClients(clients: Client[]): void {
  for (const client of clients) {
    const record = database.lookup(client.id);
    if (record.isActive()) {
      email(client.email, 'Welcome!');
    }
  }
}

function emailActiveClients(clients: Client[]): void {
  const activeClients = getActiveClients(clients);
  activeClients.forEach(client => sendWelcomeEmail(client));
}

function getActiveClients(clients: Client[]): Client[] {
  return clients.filter(client => isClientActive(client.id));
}

function isClientActive(clientId: number): boolean {
  const record = database.lookup(clientId);
  return record.isActive();
}

function sendWelcomeEmail(client: Client): void {
  email(client.email, 'Welcome!');
}

function createUser(
  name: string,
  email: string,
  age: number,
  role: string,
  department: string,
  isActive: boolean
): User {
  // ...
}

createUser('Alice', 'alice@example.com', 30, 'admin', 'engineering', true);

interface CreateUserParams {
  name: string;
  email: string;
  age: number;
  role: UserRole;
  department: string;
  isActive: boolean;
}

function createUser(params: CreateUserParams): User {
  // ...
}

createUser({
  name: 'Alice',
  email: 'alice@example.com',
  age: 30,
  role: UserRole.ADMIN,
  department: 'engineering',
  isActive: true,
});

let currentUser: User | null = null;

function checkPassword(userName: string, password: string): boolean {
  const user = database.findUser(userName);
  if (user && user.password === hash(password)) {
    // 사이드 이펙트! 비밀번호 확인 함수가 세션을 초기화한다
    currentUser = user;
    initializeSession(user);
    return true;
  }
  return false;
}

function verifyPassword(userName: string, password: string): boolean {
  const user = database.findUser(userName);
  return user !== null && user.password === hash(password);
}

function login(userName: string, password: string): LoginResult {
  if (!verifyPassword(userName, password)) {
    return { success: false };
  }
  const user = database.findUser(userName);
  const session = initializeSession(user);
  return { success: true, user, session };
}

// set이 성공 여부도 반환하고, 값도 설정한다
function setAndCheckAttribute(name: string, value: string): boolean {
  const attribute = findAttribute(name);
  if (attribute) {
    attribute.value = value;
    return true;  // 설정 + 반환
  }
  return false;
}

// 호출하는 코드가 혼란스럽다
if (setAndCheckAttribute('username', 'alice')) {
  // ???
}

function attributeExists(name: string): boolean {
  return findAttribute(name) !== null;
}

function setAttribute(name: string, value: string): void {
  const attribute = findAttribute(name);
  if (!attribute) throw new AttributeNotFoundError(name);
  attribute.value = value;
}

// 호출하는 코드가 명확하다
if (attributeExists('username')) {
  setAttribute('username', 'alice');
}

function getAdminUsers(): User[] {
  const users = database.query('SELECT * FROM users');
  return users
    .filter(u => u.role === 'admin')
    .map(u => ({ ...u, displayName: `${u.firstName} ${u.lastName}` }))
    .sort((a, b) => a.displayName.localeCompare(b.displayName));
}

function getModeratorUsers(): User[] {
  const users = database.query('SELECT * FROM users');
  return users
    .filter(u => u.role === 'moderator')
    .map(u => ({ ...u, displayName: `${u.firstName} ${u.lastName}` }))
    .sort((a, b) => a.displayName.localeCompare(b.displayName));
}

function getUsersByRole(role: UserRole): User[] {
  const users = database.query('SELECT * FROM users WHERE role = ?', [role]);
  return users
    .map(addDisplayName)
    .sort(byDisplayName);
}

function addDisplayName(user: User): User {
  return { ...user, displayName: `${user.firstName} ${user.lastName}` };
}

function byDisplayName(a: User, b: User): number {
  return a.displayName.localeCompare(b.displayName);
}

// 사용자 이름을 가져온다
const userName = user.getName();

// 배열을 순회한다
for (const item of items) {
  // 아이템을 처리한다
  processItem(item);
}

// 1을 더한다
count += 1;

// 외부 API 제한으로 최대 100건까지만 요청 가능 (API docs: https://...)
const MAX_BATCH_SIZE = 100;

// 레거시 시스템 호환을 위해 ISO-8859-1로 인코딩해야 함
// 새 시스템 전환 후 UTF-8로 변경 예정 (JIRA-4521)
const encodedData = encode(data, 'ISO-8859-1');

// 동시성 이슈로 인해 락을 먼저 획득해야 함
// 자세한 내용: https://wiki.internal/concurrency-fix-2024
await acquireLock(resourceId);

/**
 * 생성자
 */
constructor() {}

/**
 * id를 반환한다
 * @returns id
 */
getId(): number {
  return this.id;
}

// 기본 생성자
// 이 클래스는 사용자를 나타냅니다
// 작성자: 홍길동
// 작성일: 2024-01-01
// 수정일: 2024-06-15
// 수정자: 김철수

// 주석이 필요 없을 만큼 명확한 코드
class User {
  constructor(
    private readonly id: number,
    private readonly name: string,
  ) {}

  getId(): number {
    return this.id;
  }
}

// TODO 나중에 고치기
// FIXME 이거 작동 안 함
// HACK 임시로 이렇게 함
// XXX 위험한 코드

// TODO(team-auth): OAuth2 토큰 갱신 로직 추가 [JIRA-1234] @2025-Q2
// FIXME(alice): 동시 요청 시 race condition 발생. 분산 락 도입 필요 [JIRA-5678]
// HACK: Safari 17.2 flexbox 버그 워크어라운드. Safari 18에서 수정 예정 후 제거

// TODO(담당자/팀): 설명 [이슈번호] @예상시기
// FIXME(담당자): 버그 설명 [이슈번호]
// HACK: 워크어라운드 설명. 제거 조건 명시

/**
 * 주어진 기간 동안의 사용자 활동 통계를 계산합니다.
 *
 * @param userId - 통계를 조회할 사용자 ID
 * @param startDate - 조회 시작일 (포함)
 * @param endDate - 조회 종료일 (포함)
 * @returns 활동 통계 객체
 * @throws {UserNotFoundError} 사용자가 존재하지 않는 경우
 * @throws {InvalidDateRangeError} 시작일이 종료일보다 나중인 경우
 *
 * @example
 * const stats = await getUserActivityStats('user-123', '2025-01-01', '2025-03-31');
 * console.log(stats.totalLogins); // 45
 */
async function getUserActivityStats(
  userId: string,
  startDate: string,
  endDate: string,
): Promise<ActivityStats> {
  // ...
}

def get_user_activity_stats(
    user_id: str,
    start_date: str,
    end_date: str,
) -> ActivityStats:
    """주어진 기간 동안의 사용자 활동 통계를 계산합니다.

    Args:
        user_id: 통계를 조회할 사용자 ID
        start_date: 조회 시작일 (포함, ISO 8601 형식)
        end_date: 조회 종료일 (포함, ISO 8601 형식)

    Returns:
        ActivityStats: 활동 통계 객체

    Raises:
        UserNotFoundError: 사용자가 존재하지 않는 경우
        InvalidDateRangeError: 시작일이 종료일보다 나중인 경우

    Example:
        >>> stats = get_user_activity_stats('user-123', '2025-01-01', '2025-03-31')
        >>> stats.total_logins
        45
    """
    ...

function withdraw(account: Account, amount: number): number {
  if (amount > account.balance) return -1;  // 잔액 부족
  if (amount < 0) return -2;                // 음수 금액
  if (account.isFrozen) return -3;          // 계좌 동결

  account.balance -= amount;
  return 0;  // 성공
}

// 호출하는 코드
const result = withdraw(myAccount, 100);
if (result === -1) {
  // 잔액 부족 처리
} else if (result === -2) {
  // 음수 금액 처리
} else if (result === -3) {
  // 동결 계좌 처리
}

class InsufficientFundsError extends Error {
  constructor(public readonly balance: number, public readonly amount: number) {
    super(`Insufficient funds: balance ${balance}, requested ${amount}`);
    this.name = 'InsufficientFundsError';
  }
}

class AccountFrozenError extends Error {
  constructor(public readonly accountId: string) {
    super(`Account ${accountId} is frozen`);
    this.name = 'AccountFrozenError';
  }
}

function withdraw(account: Account, amount: number): void {
  if (amount < 0) throw new InvalidAmountError(amount);
  if (account.isFrozen) throw new AccountFrozenError(account.id);
  if (amount > account.balance) throw new InsufficientFundsError(account.balance, amount);

  account.balance -= amount;
}

// 호출하는 코드
try {
  withdraw(myAccount, 100);
} catch (error) {
  if (error instanceof InsufficientFundsError) {
    showAlert(`잔액이 부족합니다. 현재 잔액: ${error.balance}`);
  }
}

function processPayment(orderId: string, amount: number): PaymentResult {
  // ... 100줄의 로직 ...

  // 마지막에서야 입력값 검증
  if (!orderId) {
    return { success: false, error: 'Invalid order ID' };
  }
  if (amount < 0) {
    return { success: false, error: 'Invalid amount' };
  }

  // ... 실제 결제 처리 ...
}

function processPayment(orderId: string, amount: number): PaymentResult {
  // 가드 절(Guard Clause): 가장 먼저 검증
  if (!orderId) throw new InvalidArgumentError('orderId is required');
  if (amount <= 0) throw new InvalidArgumentError('amount must be positive');

  // 핵심 로직만 남는다
  const order = orderRepository.findById(orderId);
  if (!order) throw new OrderNotFoundError(orderId);

  return paymentGateway.charge(order, amount);
}

// 에러 계층 구조
abstract class AppError extends Error {
  abstract readonly statusCode: number;
  abstract readonly isOperational: boolean;

  constructor(message: string, public readonly cause?: Error) {
    super(message);
    this.name = this.constructor.name;
    Error.captureStackTrace(this, this.constructor);
  }
}

class NotFoundError extends AppError {
  readonly statusCode = 404;
  readonly isOperational = true;
}

class ValidationError extends AppError {
  readonly statusCode = 400;
  readonly isOperational = true;

  constructor(
    message: string,
    public readonly field: string,
    public readonly value: unknown,
  ) {
    super(message);
  }
}

class DatabaseError extends AppError {
  readonly statusCode = 500;
  readonly isOperational = false;  // 시스템 에러 — 운영자에게 알림
}

class AppError(Exception):
    """애플리케이션 기본 에러"""
    status_code: int = 500
    is_operational: bool = True

    def __init__(self, message: str, cause: Exception | None = None):
        super().__init__(message)
        self.cause = cause


class NotFoundError(AppError):
    status_code = 404


class ValidationError(AppError):
    status_code = 400

    def __init__(self, message: str, field: str, value: object):
        super().__init__(message)
        self.field = field
        self.value = value


class DatabaseError(AppError):
    status_code = 500
    is_operational = False

try {
  const data = await fetchUserData(userId);
  await processData(data);
  await saveToDatabase(data);
} catch (error) {
  // 모든 에러를 무시한다! 네트워크 에러? DB 에러? 타입 에러? 전부 삼킨다
  console.log('Something went wrong');
}

try {
  const data = await fetchUserData(userId);
  await processData(data);
  await saveToDatabase(data);
} catch (error) {
  if (error instanceof NetworkError) {
    logger.warn('Network error fetching user data', { userId, error });
    await retryWithBackoff(() => fetchUserData(userId));
  } else if (error instanceof ValidationError) {
    logger.error('Invalid user data', { userId, field: error.field });
    throw error;  // 상위로 전파
  } else if (error instanceof DatabaseError) {
    logger.fatal('Database error', { error });
    alertOpsTeam(error);
    throw error;
  } else {
    // 예상하지 못한 에러는 반드시 re-throw
    throw error;
  }
}

import { Logger } from './logger';
import { Database } from './database';
import { UserRepository } from './repositories/user';
const MAX_RETRIES = 3;
const logger = new Logger('UserService');
export class UserService {
  private db: Database;
  private repo: UserRepository;
  constructor(db: Database) {
    this.db = db;
    this.repo = new UserRepository(db);
  }
  async getUser(id: string): Promise<User> {
    const user = await this.repo.findById(id);
    if (!user) throw new NotFoundError('User not found');
    return user;
  }
  async createUser(data: CreateUserDTO): Promise<User> {
    const existing = await this.repo.findByEmail(data.email);
    if (existing) throw new ConflictError('Email already exists');
    return this.repo.create(data);
  }
}

import { Logger } from './logger';
import { Database } from './database';
import { UserRepository } from './repositories/user';

const MAX_RETRIES = 3;
const logger = new Logger('UserService');

export class UserService {
  private db: Database;
  private repo: UserRepository;

  constructor(db: Database) {
    this.db = db;
    this.repo = new UserRepository(db);
  }

  async getUser(id: string): Promise<User> {
    const user = await this.repo.findById(id);
    if (!user) throw new NotFoundError('User not found');
    return user;
  }

  async createUser(data: CreateUserDTO): Promise<User> {
    const existing = await this.repo.findByEmail(data.email);
    if (existing) throw new ConflictError('Email already exists');
    return this.repo.create(data);
  }
}

// 1. 가장 먼저: 퍼블릭 인터페이스 (헤드라인)
export class OrderProcessor {
  async processOrder(orderId: string): Promise<OrderResult> {
    const order = await this.validateAndFetchOrder(orderId);
    const pricing = this.calculatePricing(order);
    return this.executePayment(order, pricing);
  }

  // 2. 중간: 비즈니스 로직 (핵심 내용)
  private async validateAndFetchOrder(orderId: string): Promise<Order> {
    const order = await this.orderRepo.findById(orderId);
    if (!order) throw new OrderNotFoundError(orderId);
    this.validateOrderState(order);
    return order;
  }

  private calculatePricing(order: Order): Pricing {
    const subtotal = this.sumItems(order.items);
    const discount = this.applyDiscounts(subtotal, order.coupons);
    const tax = this.calculateTax(subtotal - discount);
    return { subtotal, discount, tax, total: subtotal - discount + tax };
  }

  // 3. 마지막: 세부 구현 (디테일)
  private validateOrderState(order: Order): void { /* ... */ }
  private sumItems(items: OrderItem[]): number { /* ... */ }
  private applyDiscounts(amount: number, coupons: Coupon[]): number { /* ... */ }
  private calculateTax(amount: number): number { /* ... */ }
}

// 1. Node.js 내장 모듈
import { readFile } from 'fs/promises';
import path from 'path';

// 2. 외부 라이브러리 (node_modules)
import express from 'express';
import { z } from 'zod';

// 3. 내부 모듈 — 절대 경로
import { AppConfig } from '@/config';
import { Logger } from '@/utils/logger';

// 4. 내부 모듈 — 상대 경로
import { UserService } from './services/user';
import { OrderService } from './services/order';

// 5. 타입 Import (TypeScript)
import type { User, Order } from './types';

{
  "rules": {
    "import/order": [
      "error",
      {
        "groups": ["builtin", "external", "internal", "parent", "sibling", "type"],
        "newlines-between": "always",
        "alphabetize": { "order": "asc" }
      }
    ]
  }
}

src/
├── modules/
│   ├── user/
│   │   ├── index.ts          # 퍼블릭 API만 export
│   │   ├── user.service.ts
│   │   ├── user.repository.ts
│   │   ├── user.controller.ts
│   │   ├── user.types.ts
│   │   └── __tests__/
│   │       ├── user.service.test.ts
│   │       └── user.repository.test.ts
│   ├── order/
│   │   ├── index.ts
│   │   ├── order.service.ts
│   │   └── ...
│   └── payment/
│       ├── index.ts
│       └── ...
├── shared/
│   ├── errors/
│   ├── utils/
│   └── types/
└── infrastructure/
    ├── database/
    ├── cache/
    └── messaging/

// modules/user/index.ts — 퍼블릭 API만 노출
export { UserService } from './user.service';
export type { User, CreateUserDTO } from './user.types';
// UserRepository는 export하지 않는다 — 내부 구현

describe('UserService', () => {
  describe('createUser', () => {
    it('should create user with valid data', async () => {
      // Arrange — 테스트 데이터 준비
      const userRepo = new InMemoryUserRepository();
      const service = new UserService(userRepo);
      const userData: CreateUserDTO = {
        name: 'Alice',
        email: 'alice@example.com',
      };

      // Act — 테스트 대상 실행
      const result = await service.createUser(userData);

      // Assert — 결과 검증
      expect(result.name).toBe('Alice');
      expect(result.email).toBe('alice@example.com');
      expect(result.id).toBeDefined();
      expect(await userRepo.count()).toBe(1);
    });
  });
});

it('should handle user lifecycle', async () => {
  // 생성, 조회, 수정, 삭제를 모두 테스트
  const user = await service.createUser(data);
  expect(user.id).toBeDefined();

  const fetched = await service.getUser(user.id);
  expect(fetched.name).toBe(data.name);

  await service.updateUser(user.id, { name: 'Bob' });
  const updated = await service.getUser(user.id);
  expect(updated.name).toBe('Bob');

  await service.deleteUser(user.id);
  await expect(service.getUser(user.id)).rejects.toThrow();
});

describe('UserService', () => {
  it('should create user and return with generated id', async () => {
    const user = await service.createUser(validUserData);
    expect(user.id).toBeDefined();
    expect(user.name).toBe(validUserData.name);
  });

  it('should retrieve existing user by id', async () => {
    const created = await service.createUser(validUserData);
    const fetched = await service.getUser(created.id);
    expect(fetched).toEqual(created);
  });

  it('should update user name', async () => {
    const user = await service.createUser(validUserData);
    await service.updateUser(user.id, { name: 'Bob' });
    const updated = await service.getUser(user.id);
    expect(updated.name).toBe('Bob');
  });

  it('should throw NotFoundError when getting deleted user', async () => {
    const user = await service.createUser(validUserData);
    await service.deleteUser(user.id);
    await expect(service.getUser(user.id)).rejects.toThrow(NotFoundError);
  });
});

it('test1', async () => {
  const r = await s.calc({ a: 100, b: 2, c: 0.1, d: true });
  expect(r).toBe(180);
});

it('should apply 10% discount when premium member orders 2 items at 100 each', async () => {
  // Given
  const order = createOrder({
    items: [{ price: 100, quantity: 2 }],
    isPremiumMember: true,
    discountRate: 0.1,
  });

  // When
  const totalPrice = await pricingService.calculateTotal(order);

  // Then
  expect(totalPrice).toBe(180); // (100 * 2) - 10% discount = 180
});

describe('PasswordValidator', () => {
  // Good: 시나리오가 명확하다
  it('should return valid when password has 8+ chars with mixed case and numbers', () => {});
  it('should return invalid when password is shorter than 8 characters', () => {});
  it('should return invalid when password lacks uppercase letters', () => {});
  it('should return invalid when password lacks numbers', () => {});
  it('should throw EmptyPasswordError when password is empty string', () => {});
});

class TestPasswordValidator:
    def test_valid_password_with_mixed_case_and_numbers(self):
        """8자 이상, 대소문자 혼합, 숫자 포함 시 유효"""
        ...

    def test_invalid_when_shorter_than_8_chars(self):
        """8자 미만 비밀번호는 무효"""
        ...

    def test_raises_error_when_password_is_empty(self):
        """빈 문자열 입력 시 에러 발생"""
        ...

function getPaymentAmount(employee: Employee): number {
  let result: number;
  if (employee.isSeparated) {
    result = separatedAmount();
  } else {
    if (employee.isRetired) {
      result = retiredAmount();
    } else {
      result = normalPayAmount();
    }
  }
  return result;
}

function getPaymentAmount(employee: Employee): number {
  if (employee.isSeparated) return separatedAmount();
  if (employee.isRetired) return retiredAmount();
  return normalPayAmount();
}

function calculateShippingCost(order: Order): number {
  if (order.shippingMethod === 'standard') {
    return order.weight * 1.5;
  } else if (order.shippingMethod === 'express') {
    return order.weight * 3.0 + 5;
  } else if (order.shippingMethod === 'overnight') {
    return order.weight * 5.0 + 15;
  } else if (order.shippingMethod === 'international') {
    return order.weight * 10.0 + 25;
  }
  throw new Error('Unknown shipping method');
}

interface ShippingStrategy {
  calculate(weight: number): number;
}

const shippingStrategies: Record<string, ShippingStrategy> = {
  standard: { calculate: (w) => w * 1.5 },
  express: { calculate: (w) => w * 3.0 + 5 },
  overnight: { calculate: (w) => w * 5.0 + 15 },
  international: { calculate: (w) => w * 10.0 + 25 },
};

function calculateShippingCost(order: Order): number {
  const strategy = shippingStrategies[order.shippingMethod];
  if (!strategy) throw new UnknownShippingMethodError(order.shippingMethod);
  return strategy.calculate(order.weight);
}

function getActiveAdminEmails(users: User[]): string[] {
  const result: string[] = [];
  for (let i = 0; i < users.length; i++) {
    if (users[i].isActive) {
      if (users[i].role === 'admin') {
        result.push(users[i].email.toLowerCase());
      }
    }
  }
  result.sort();
  return result;
}

function getActiveAdminEmails(users: User[]): string[] {
  return users
    .filter(user => user.isActive)
    .filter(user => user.role === 'admin')
    .map(user => user.email.toLowerCase())
    .sort();
}

// 인지 복잡도: 13 (높음!)
function processData(items: Item[]): Result[] {   // +0
  const results: Result[] = [];
  for (const item of items) {                     // +1 (루프)
    if (item.isValid) {                           // +2 (if + 중첩1)
      if (item.type === 'A') {                    // +3 (if + 중첩2)
        results.push(processTypeA(item));
      } else if (item.type === 'B') {             // +1 (else if)
        for (const sub of item.children) {        // +4 (루프 + 중첩3)
          if (sub.isActive) {                     // +5 (if + 중첩4) -- 이미 이해 불가
            results.push(processTypeB(sub));
          }
        }
      }
    }
  }
  return results;                                 // 총: 1+2+3+1+4+5 = 16
}

function processData(items: Item[]): Result[] {
  return items
    .filter(item => item.isValid)
    .flatMap(item => processByType(item));
}

function processByType(item: Item): Result[] {
  switch (item.type) {                            // +1
    case 'A': return [processTypeA(item)];
    case 'B': return processActiveBChildren(item);
    default: return [];
  }
}

function processActiveBChildren(item: Item): Result[] {
  return item.children
    .filter(child => child.isActive)
    .map(child => processTypeB(child));
}

## 네이밍
- [ ] 변수/함수/클래스 이름이 의도를 드러내는가?
- [ ] 약어를 사용하지 않았는가?
- [ ] 팀 네이밍 컨벤션을 따르는가?

## 함수
- [ ] 함수가 한 가지 일만 하는가?
- [ ] 매개변수가 3개 이하인가?
- [ ] 사이드 이펙트가 없는가?

## 에러 처리
- [ ] 적절한 커스텀 에러를 사용하는가?
- [ ] 에러를 삼키지 않는가?
- [ ] 가드 절로 빠르게 실패하는가?

## 테스트
- [ ] 새 기능에 대한 테스트가 있는가?
- [ ] 엣지 케이스를 커버하는가?
- [ ] 테스트 이름이 시나리오를 설명하는가?

## 코드 구조
- [ ] 파일이 400줄을 넘지 않는가?
- [ ] 중첩 깊이가 3단계 이하인가?
- [ ] DRY 원칙을 따르는가?

## 보안
- [ ] 사용자 입력을 검증하는가?
- [ ] SQL 인젝션, XSS 가능성은 없는가?
- [ ] 민감 정보를 로그에 남기지 않는가?

// Bad: 한 클래스가 여러 책임
class UserService {
  createUser(data: CreateUserDTO) {}      // 비즈니스 로직
  sendEmail(to: string, body: string) {}  // 이메일 전송
  generatePDF(user: User) {}              // PDF 생성
  logAction(action: string) {}            // 로깅
}

// Good: 각 클래스가 하나의 책임
class UserService { createUser(data: CreateUserDTO) {} }
class EmailService { send(to: string, body: string) {} }
class PDFGenerator { generate(user: User) {} }
class AuditLogger { log(action: string) {} }

// 확장에는 열려 있고, 수정에는 닫혀 있어야 한다
interface PaymentProcessor {
  process(amount: number): Promise<PaymentResult>;
}

class StripeProcessor implements PaymentProcessor {
  async process(amount: number) { /* Stripe API */ }
}

class PayPalProcessor implements PaymentProcessor {
  async process(amount: number) { /* PayPal API */ }
}

// 새 결제 수단 추가 시 기존 코드 수정 없이 새 클래스만 추가
class CryptoProcessor implements PaymentProcessor {
  async process(amount: number) { /* Crypto API */ }
}

// 하위 타입은 상위 타입을 대체할 수 있어야 한다
class Bird {
  fly(): void { /* 날아간다 */ }
}

// Bad: 펭귄은 날 수 없으므로 Bird를 상속하면 안 된다
class Penguin extends Bird {
  fly(): void { throw new Error('Cannot fly!'); }
}

// Good: 인터페이스 분리
interface FlyingBird { fly(): void; }
interface SwimmingBird { swim(): void; }

class Eagle implements FlyingBird { fly() {} }
class Penguin implements SwimmingBird { swim() {} }

// Bad: 뚱뚱한 인터페이스
interface Worker {
  work(): void;
  eat(): void;
  sleep(): void;
  attendMeeting(): void;
}

// Good: 분리된 인터페이스
interface Workable { work(): void; }
interface Feedable { eat(): void; }
interface Meetable { attendMeeting(): void; }

class Developer implements Workable, Feedable, Meetable {
  work() {}
  eat() {}
  attendMeeting() {}
}

class Robot implements Workable {
  work() {}
  // eat(), attendMeeting() 필요 없음
}

// Bad: 고수준 모듈이 저수준 모듈에 직접 의존
class OrderService {
  private mysqlDb = new MySQLDatabase();  // 구체 클래스에 의존

  save(order: Order) {
    this.mysqlDb.insert('orders', order);
  }
}

// Good: 추상화에 의존
interface OrderRepository {
  save(order: Order): Promise<void>;
  findById(id: string): Promise<Order | null>;
}

class OrderService {
  constructor(private readonly repo: OrderRepository) {}

  async save(order: Order) {
    await this.repo.save(order);
  }
}

// 구체 구현은 별도로
class MySQLOrderRepository implements OrderRepository { /* ... */ }
class MongoOrderRepository implements OrderRepository { /* ... */ }
class InMemoryOrderRepository implements OrderRepository { /* ... */ }  // 테스트용

{
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "prettier"
  ],
  "rules": {
    "max-lines": ["warn", { "max": 400 }],
    "max-lines-per-function": ["warn", { "max": 50 }],
    "max-params": ["warn", { "max": 3 }],
    "max-depth": ["warn", { "max": 3 }],
    "complexity": ["warn", { "max": 10 }],
    "no-else-return": "error",
    "prefer-const": "error",
    "no-var": "error"
  }
}

# sonar-project.properties
sonar.qualitygate.conditions:
  - metric: cognitive_complexity
    operator: GT
    error: 15
  - metric: duplicated_lines_density
    operator: GT
    error: 3
  - metric: coverage
    operator: LT
    error: 80