---
name: Readability (Misc)
description: 가독성 기타 원칙. 복잡한 조건 이름 붙이기, 매직 넘버 금지, 함수 이름과 부수효과 일치, 삼항 연산자 중첩 금지.
type: coding-standard
category: readability
---

> 출처: 팀 공통 원칙 문서 `principles/` 2026-07-03 발췌. 원칙 개정은 원본(팀 공통 문서) 먼저, 이 사본은 따라간다.

# 가독성 기타

## P-020 복잡한 조건에 이름 붙이기

복잡한 boolean 표현식은 의미 있는 변수명으로 추출한다.

이름 붙이는 기준:

- 조건이 복잡할 때
- 조건이 재사용될 때
- 단위 테스트가 필요할 때

단순하고 한 번만 쓰는 조건은 불필요하다.

```typescript
// ❌ 한눈에 파악하기 어렵다
const result = products.filter((product) =>
  product.categories.some(
    (category) =>
      category.id === targetCategory.id &&
      product.prices.some((price) => price >= minPrice && price <= maxPrice)
  )
);

// ✅ 의미 단위로 이름을 붙인다
const matchedProducts = products.filter((product) => {
  return product.categories.some((category) => {
    const isSameCategory = category.id === targetCategory.id;
    const isPriceInRange = product.prices.some(
      (price) => price >= minPrice && price <= maxPrice
    );
    return isSameCategory && isPriceInRange;
  });
});
```

## P-021 매직 넘버 금지

의도를 알 수 없는 숫자는 이름 있는 상수로 추출한다.
이름이 있으면 응집도도 높아진다 — 애니메이션을 바꿀 때 지연 시간도 함께 수정된다.

```typescript
// ❌ 300이 무슨 의미인지 모른다
await delay(300);

// ✅ 의도가 드러나고, 애니메이션 변경 시 함께 수정됨
const ANIMATION_DELAY_MS = 300;
await delay(ANIMATION_DELAY_MS);
```

## P-022 함수 이름은 부수효과 포함해서 표현

함수 이름이 실제 동작(side effect 포함)을 완전히 설명해야 한다.
이름이 동작과 불일치하면 호출자가 예상 못한 결과를 만난다.

```typescript
// ❌ getUser인데 실제로는 로깅과 캐시 업데이트도 한다
async function getUser(id: string) {
  const user = await fetchUser(id);
  analytics.track('user_fetched'); // 숨은 부수 효과
  cache.set(`user:${id}`, user); // 숨은 부수 효과
  return user;
}

// ✅ 부수 효과가 있다면 분리하거나 이름에 반영
async function fetchUser(id: string) {
  return await api.get(`/users/${id}`);
}
// 호출부에서 명시적으로
const user = await fetchUser(id);
analytics.track('user_fetched');
```

## P-023 삼항 연산자 중첩 금지

중첩된 삼항 연산자는 IIFE + if문으로 풀어 명확하게 만든다.

```typescript
// ❌ 중첩 삼항 — 조건 구조 파악 어렵다
const status = A && B ? 'BOTH' : A || B ? (A ? 'A' : 'B') : 'NONE';

// ✅ IIFE로 if문 사용 — 조건 흐름이 명확하다
const status = (() => {
  if (A && B) {
    return 'BOTH';
  }
  if (A) {
    return 'A';
  }
  if (B) {
    return 'B';
  }
  return 'NONE';
})();
```