코드 품질 = 개발자의 품격

GitHub 레포를 공개한다는 것은 자신의 코딩 실력을 세상에 공개한다는 뜻이다.

채용 담당자 중 일부는 실제로 코드를 본다.

코드에서 판단하는 것:
━━━━━━━━━━━━━━━━━━
1. 파일/폴더 구조가 정리되어 있는가?
2. 함수/클래스명이 의미 있는가?
3. 주석과 docstring이 적절한가?
4. 에러 처리가 되어 있는가?
5. requirements.txt / pyproject.toml이 있는가?

---

코드 정리 체크리스트

1. 파일 구조

나쁜 구조:
├── app.py (모든 코드 1,500줄)
├── test.py (빈 파일)
└── stuff.py (이름이 뭐야?)

좋은 구조:
├── app/
│   ├── __init__.py
│   ├── main.py           # FastAPI 진입점
│   ├── routers/           # API 라우터
│   ├── agents/            # LangGraph 에이전트
│   ├── rag/               # RAG 파이프라인
│   ├── kg/                # Knowledge Graph
│   └── models/            # Pydantic 모델
├── tests/
│   ├── test_diagnosis.py
│   └── test_rag.py
├── scripts/               # 유틸리티 스크립트
├── docs/                   # 문서
├── requirements.txt
├── .env.example
├── docker compose.yml
└── README.md

2. 함수명과 변수명

# 나쁜 예
def do_stuff(x, y):
    d = get_data(x)
    r = process(d, y)
    return r

# 좋은 예
def diagnose_equipment_error(error_code: str, include_history: bool = True) -> DiagnosisResult:
    """설비 에러코드를 기반으로 진단 결과를 반환한다."""
    kg_context = query_knowledge_graph(error_code)
    rag_context = search_manuals(error_code)
    return generate_diagnosis(kg_context, rag_context, include_history)

3. 주석과 Docstring

# 나쁜 주석
x = 85  # 85로 설정

# 좋은 주석
# KOSHA H-72-2024 제3장 2절 기준: 베어링 온도 85도 초과 시 즉시 점검
TEMP_THRESHOLD = 85.0

4. requirements.txt

# 버전 고정 (재현성 보장)
langchain==1.0.0
langchain-openai==0.3.0
neo4j==5.28.0
chromadb==1.4.0
fastapi==0.115.0
uvicorn==0.32.0
pydantic==2.11.0

---

최종 점검 명령어

# 1. 코드 포맷팅 (black)
pip install black
black app/ --check

# 2. 임포트 정리 (isort)
pip install isort
isort app/ --check

# 3. 린트 (flake8)
pip install flake8
flake8 app/ --max-line-length 120

# 4. 타입 체크 (mypy, 선택)
pip install mypy
mypy app/ --ignore-missing-imports

# 5. 보안 점검 (bandit)
pip install bandit
bandit -r app/

---

핵심 정리

1. 파일 구조는 역할별로 명확히 분리
2. 함수명은 동사 + 목적어 (diagnose_equipment_error)
3. 주석은 **왜(Why)**를 설명 (코드는 What을 이미 보여준다)
4. requirements.txt에 버전 고정 필수