재사용 코드 코딩 컨벤션

02-reusable-code/ (TypeScript/React), 02-reusable-code-python/ (Python), 02-reusable-code-java/ (Java/Spring Boot) 공통 규칙

공통 규칙

파일 메타데이터

모든 커스텀 파일에 출처·버전 메타데이터를 포함한다.

TypeScript — JSDoc 헤더:

/**
 * 파일 설명
 *
 * @source 출처-프로젝트명
 * @extracted YYYY-MM-DD
 * @version X.Y.Z
 *
 * @dependencies 의존성 목록
 */

Python — 모듈 독스트링:

"""
한줄 요약 - 모듈의 핵심 기능 설명

@source 출처-프로젝트명
@extracted YYYY-MM-DD
@version X.Y.Z

의존성:
    - 패키지명 (필수/권장/선택)
    - 패키지명 (pip install 패키지명)

사용법:
    from module import function

    result = function(args)
"""

• @source: 코드가 추출된 원본 프로젝트명
• @extracted: 추출 날짜
• @version: 시맨틱 버전
• Python은 의존성(필수/권장/선택 구분)과 사용법(최소 1개 실행 가능 예제) 포함

주석 언어

• 한국어 사용
• 에러 메시지 문자열은 영어 허용

import 순서 원칙

그룹 간 빈 줄로 구분:

TypeScript / React 규칙

일반 규칙

shadcn 컴포넌트 예외 정책

• 01-ui-components/shadcn-* 하위 개별 컴포넌트 파일은 업스트림 스타일 유지
• 이유: 향후 업스트림 업데이트 시 diff/merge 용이
• index.ts 배럴 파일만 한국어 주석 + 출처 표시

Python 규칙

import 순서

PEP8 기준, 그룹 간 빈 줄:

# 1. 표준 라이브러리
import logging
import zipfile
from pathlib import Path

# 2. 서드파티
import numpy as np
import pandas as pd

# 3. 로컬
from .utils import helper_function

타입 힌트

Python 3.10+ 내장 타입 문법 사용:

# 올바른 예
def process(items: list[str]) -> dict[str, int]: ...
def load(path: str | Path) -> bytes | None: ...

# 금지 (구식)
from typing import Dict, List, Tuple, Union

• dict, list, tuple, set → 내장 타입 사용
• Union[A, B] → A | B 사용
• Optional[T] → T | None 사용
• Any → typing에서 import 허용 (대안 없음)

독스트링 (함수/클래스)

Google 스타일, 한국어:

def function_name(param: str, count: int = 0) -> list[str]:
    """함수 한줄 요약

    Args:
        param: 매개변수 설명
        count: 매개변수 설명 (기본값: 0)

    Returns:
        반환값 설명

    Raises:
        ValueError: 발생 조건
    """

로깅

모든 모듈에 로거 설정:

import logging

logger = logging.getLogger(__name__)

• 메시지는 한국어
• print() 금지 (__main__ 블록 제외)
• 레벨: debug (디버그), info (정상 동작), warning (주의), error (오류)

에러 처리

try:
    result = risky_operation()
except SpecificError as e:
    logger.error("작업 실패: %s", e)
    raise  # 또는 적절한 복구

• 범용 except Exception 최소화
• 리소스는 try/finally 또는 컨텍스트 매니저로 반드시 정리
• 파일 존재/유효성 검증은 호출자 책임 (모듈 내부에서 중복 검증하지 않음)

네이밍 규칙

따옴표

• 큰따옴표 " 사용

줄 길이

• 기준: 88자 (Black 기본값)
• 함수 시그니처가 길 경우 매개변수별 줄바꿈:

def generate_section_xml(
    title: str,
    content: str,
    tables: list[dict[str, Any]] | None = None,
    header_org: str = "기본값",
) -> str:

__init__.py

• 명시적 import + __all__ 리스트 필수
• 모듈 독스트링 포함 (메타데이터 태그)

"""
패키지 설명

@source 출처
@extracted YYYY-MM-DD
@version X.Y.Z
"""

from .module import function_a, function_b

__all__ = [
    "function_a",
    "function_b",
]

싱글톤 패턴

모듈 레벨 _instance + get_*() 팩토리 함수:

_instance: MyClass | None = None

def get_instance(**kwargs) -> MyClass:
    """싱글톤 인스턴스 반환"""
    global _instance
    if _instance is None:
        _instance = MyClass(**kwargs)
    return _instance

리소스 관리

• 파일/네트워크/DB 연결은 반드시 with 또는 try/finally로 정리
• read_only=True 워크북도 반드시 .close() 호출

# 올바른 예
wb = load_workbook(path, read_only=True)
try:
    return wb.sheetnames
finally:
    wb.close()

Java / Spring Boot 규칙

파일 메타데이터

Javadoc 헤더:

/**
 * 파일 설명 (한국어)
 *
 * @source 출처-프로젝트명
 * @extracted YYYY-MM-DD
 * @version X.Y.Z
 *
 * @dependencies 의존성 목록
 */

패키지 규칙

• 범용 패키지: com.example.app.* (실제 프로젝트 적용 시 변경)
• 카테고리별 하위 패키지: config, security, exception, util, service, domain

네이밍 규칙

주석 언어

• 한국어 사용 (Javadoc, 인라인 주석 모두)
• 에러 메시지 문자열은 영어 허용

import 순서

그룹 간 빈 줄로 구분:

// 1. java/jakarta 표준 라이브러리
import java.time.LocalDateTime;
import jakarta.servlet.http.HttpServletRequest;

// 2. Spring 프레임워크
import org.springframework.stereotype.Service;
import org.springframework.security.core.userdetails.UserDetails;

// 3. 서드파티
import com.github.benmanes.caffeine.cache.Caffeine;
import lombok.RequiredArgsConstructor;

// 4. 프로젝트 내부
import com.example.app.domain.User;
import com.example.app.exception.BusinessException;

Lombok 사용 규칙

• @RequiredArgsConstructor + private final 필드 (생성자 주입)
• @Getter, @Builder 허용
• @Data 지양 (DTO에만 제한적 허용)
• @Setter 금지 (도메인 엔티티)

예외 처리

// 비즈니스 예외는 커스텀 예외 사용
throw new BusinessException("유효하지 않은 요청입니다");

// 리소스 미발견
throw new ResourceNotFoundException("사용자를 찾을 수 없습니다: " + id);

설정 파일 패턴

• @Value 또는 @ConfigurationProperties로 외부 설정 주입
• 하드코딩 금지 (URL, 포트, 경로, 자격증명)
• 프로파일별 설정 분리 (application-{profile}.yml)

버전 전략

시맨틱 버전 (@version)

shadcn 컴포넌트 버전

• @version은 shadcn/ui 릴리스 버전을 따름 (현재 v4)
• 커스텀 수정 시 @version 4.0.0-custom.1 형태 사용

호환성

적용 이력