코딩 표준 및 모범 사례

모든 프로젝트에 적용 가능한 범용 코딩 표준.

활성화 시점

• 새 프로젝트 또는 모듈을 시작할 때
• 코드 품질 및 유지보수성을 검토할 때
• 기존 코드를 컨벤션에 맞게 리팩터링할 때
• 네이밍, 포맷팅 또는 구조적 일관성을 적용할 때
• 린팅, 포맷팅 또는 타입 검사 규칙을 설정할 때
• 새 기여자에게 코딩 컨벤션을 안내할 때

코드 품질 원칙

1. 가독성 우선

• 코드는 작성보다 읽히는 횟수가 더 많다
• 명확한 변수 및 함수 이름 사용
• 주석보다 자기 문서화 코드를 선호
• 일관된 포맷팅 유지

2. KISS (Keep It Simple, Stupid)

• 동작하는 가장 단순한 해결책
• 과도한 엔지니어링 지양
• 조기 최적화 금지
• 이해하기 쉬운 코드 > 영리한 코드

3. DRY (Don't Repeat Yourself)

• 공통 로직을 함수로 추출
• 재사용 가능한 컴포넌트 생성
• 모듈 간 유틸리티 공유
• 복사-붙여넣기 프로그래밍 지양

4. YAGNI (You Aren't Gonna Need It)

• 필요하기 전에 기능을 만들지 않기
• 추측에 의한 일반화 지양
• 필요할 때만 복잡성 추가
• 단순하게 시작하고 필요할 때 리팩터링

TypeScript/JavaScript 표준

변수 네이밍

// PASS: GOOD: Descriptive names
const marketSearchQuery = 'election'
const isUserAuthenticated = true
const totalRevenue = 1000

// FAIL: BAD: Unclear names
const q = 'election'
const flag = true
const x = 1000

함수 네이밍

// PASS: GOOD: Verb-noun pattern
async function fetchMarketData(marketId: string) { }
function calculateSimilarity(a: number[], b: number[]) { }
function isValidEmail(email: string): boolean { }

// FAIL: BAD: Unclear or noun-only
async function market(id: string) { }
function similarity(a, b) { }
function email(e) { }

불변성 패턴 (필수)

// PASS: ALWAYS use spread operator
const updatedUser = {
  ...user,
  name: 'New Name'
}

const updatedArray = [...items, newItem]

// FAIL: NEVER mutate directly
user.name = 'New Name'  // BAD
items.push(newItem)     // BAD

에러 처리

// PASS: GOOD: Comprehensive error handling
async function fetchData(url: string) {
  try {
    const response = await fetch(url)

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`)
    }

    return await response.json()
  } catch (error) {
    console.error('Fetch failed:', error)
    throw new Error('Failed to fetch data')
  }
}

// FAIL: BAD: No error handling
async function fetchData(url) {
  const response = await fetch(url)
  return response.json()
}

Async/Await 모범 사례

// PASS: GOOD: Parallel execution when possible
const [users, markets, stats] = await Promise.all([
  fetchUsers(),
  fetchMarkets(),
  fetchStats()
])

// FAIL: BAD: Sequential when unnecessary
const users = await fetchUsers()
const markets = await fetchMarkets()
const stats = await fetchStats()

타입 안전성

// PASS: GOOD: Proper types
interface Market {
  id: string
  name: string
  status: 'active' | 'resolved' | 'closed'
  created_at: Date
}

function getMarket(id: string): Promise<Market> {
  // Implementation
}

// FAIL: BAD: Using 'any'
function getMarket(id: any): Promise<any> {
  // Implementation
}

React 모범 사례

컴포넌트 구조

// PASS: GOOD: Functional component with types
interface ButtonProps {
  children: React.ReactNode
  onClick: () => void
  disabled?: boolean
  variant?: 'primary' | 'secondary'
}

export function Button({
  children,
  onClick,
  disabled = false,
  variant = 'primary'
}: ButtonProps) {
  return (
    <button
      onClick={onClick}
      disabled={disabled}
      className={`btn btn-${variant}`}
    >
      {children}
    </button>
  )
}

// FAIL: BAD: No types, unclear structure
export function Button(props) {
  return <button onClick={props.onClick}>{props.children}</button>
}

커스텀 Hook

// PASS: GOOD: Reusable custom hook
export function useDebounce<T>(value: T, delay: number): T {
  const [debouncedValue, setDebouncedValue] = useState<T>(value)

  useEffect(() => {
    const handler = setTimeout(() => {
      setDebouncedValue(value)
    }, delay)

    return () => clearTimeout(handler)
  }, [value, delay])

  return debouncedValue
}

// Usage
const debouncedQuery = useDebounce(searchQuery, 500)

상태 관리

// PASS: GOOD: Proper state updates
const [count, setCount] = useState(0)

// Functional update for state based on previous state

…