Featured image of post [Python Master] 29. 코드 품질 관리 - 린트/타입체크/리팩토링

[Python Master] 29. 코드 품질 관리 - 린트/타입체크/리팩토링

코드 품질을 변경 비용을 줄이는 시스템으로 정의하고, 포맷/린트/타입/테스트/보안을 역할별로 정리합니다. 자동화와 코드리뷰 체크리스트로 팀 품질을 유지하는 방법을 다룹니다.

챕터 29: 코드 품질 관리 전략

코드 품질은 “예쁜 코드”가 아니라, 변경 비용을 낮추는 시스템입니다. 도구는 수단이고, 핵심은 팀이 합의한 기준을 자동화해 “실수/회귀”를 줄이는 것입니다.

학습 목표

  • 코드 품질의 다양한 측면을 이해할 수 있다
  • 정적 분석 도구를 효과적으로 활용할 수 있다
  • 코딩 표준과 스타일 가이드를 적용할 수 있다
  • 코드 리뷰와 개발 프로세스를 개선할 수 있다

핵심 개념(이론)

1) 코드 품질 관리의 역할과 경계

이 챕터의 핵심은 “무엇을 할 수 있나”가 아니라, 어떤 문제를 해결하고 어디까지 책임지는지를 분명히 하는 것입니다. 경계가 흐리면 코드는 커질수록 결합이 늘어나고 수정 비용이 커집니다.

2) 왜 이 개념이 필요한가(실무 동기)

실무에서는 예외 상황, 성능, 협업, 테스트가 항상 문제를 만듭니다. 따라서 이 주제는 기능이 아니라 **품질(신뢰성/유지보수성/보안)**을 위한 기반으로 이해해야 합니다.

3) 트레이드오프: 간단함 vs 확장성

대부분의 선택은 “더 단순하게”와 “더 확장 가능하게” 사이에서 균형을 잡는 일입니다. 초기에는 단순함을, 장기 운영/팀 협업이 커질수록 확장성을 더 우선합니다.

4) 실패 모드(Failure Modes)를 먼저 생각하라

무엇이 실패하는지(입력, I/O, 동시성, 외부 시스템)를 먼저 떠올리면 설계가 안정적으로 변합니다. 이 챕터의 예제는 실패 모드를 축소해서 보여주므로, 실제 적용 시에는 더 많은 방어가 필요합니다.

5) 학습 포인트: 외우지 말고 “판단 기준”을 남겨라

핵심은 API를 외우는 것이 아니라, “언제 무엇을 선택할지” 판단 기준을 정리하는 것입니다. 이 기준이 쌓이면 새로운 라이브러리/도구가 나와도 빠르게 적응할 수 있습니다.

선택 기준(Decision Guide)

  • 기본은 가독성/명확성 우선(최적화는 측정 이후).
  • 외부 의존이 늘수록 경계/추상화와 테스트를 먼저 강화.
  • 복잡도가 증가하면 “규칙을 코드로”가 아니라 “구조로” 담는 방향을 고려.

흔한 오해/주의점

  • 도구/문법이 곧 실력이라는 오해가 있습니다. 실력은 문제를 단순화하고 구조화하는 능력입니다.
  • 극단적 최적화/과설계는 학습과 유지보수를 방해할 수 있습니다.

요약

  • 코드 품질 관리는 기능이 아니라 구조/품질을 위한 기반이다.
  • 트레이드오프와 실패 모드를 먼저 생각하고, 판단 기준을 남기자.

핵심 내용

코드 품질의 요소(실무 관점)

  • 가독성: 이해하기 쉬운 코드
  • 유지보수성: 변경하기 쉬운 구조
  • 신뢰성: 버그 없는 안정적 코드
  • 성능: 효율적인 실행
  • 보안: 취약점 없는 안전한 코드

여기서 중요한 건 “모두를 동시에 최대화”할 수 없다는 점입니다. 예를 들어 성능을 극단적으로 끌어올리면 가독성이 희생될 수 있고, 보안을 강화하면 개발 속도가 느려질 수 있습니다. 품질 관리의 목표는 균형점을 찾는 것입니다.

코딩 스타일과 표준

  • PEP 8: 파이썬 스타일 가이드
  • PEP 257: 독스트링 컨벤션
  • 타입 힌트: PEP 484, 526 타입 표기
  • 블랙: 코드 포매터
  • isort: 임포트 정렬

도구 체인(역할 분담)

  • formatter(형식): Black (또는 Ruff format)
  • linter(규칙/버그 패턴): Ruff, flake8, pylint
  • type checker(정적 타입): mypy, pyright
  • test runner(회귀 방지): pytest + coverage
  • security(기본 취약점 탐지): bandit, dependency audit

이 도구들을 “다 켜는 것”보다 중요한 건, 팀에서 최소 기준을 합의하고 CI에서 항상 강제하는 것입니다. 최근에는 Rust로 작성된 Ruff가 flake8·isort와 pylint 규칙 상당수를 대체하며 사실상 표준 린터/포매터로 자리잡았습니다. Ruff는 flake8보다 수십 배 빠르고 ruff format으로 Black 호환 포매팅까지 제공하므로, 신규 프로젝트라면 Ruff 단독으로 시작하고 기존에 flake8을 쓰던 팀은 점진적으로 전환하는 편이 현실적입니다.

아래는 pyproject.toml 하나에 Ruff·mypy 설정을 모아둔 예시입니다. 도구별 설정 파일을 흩어두지 않고 한곳에 모으면 신규 팀원이 규칙을 파악하기 쉽습니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

# pyproject.toml
[tool.ruff]
line-length = 100
target-version = "py311"
src = ["src", "tests"]

[tool.ruff.lint]
# E/F: pycodestyle+pyflakes(flake8 대체), I: import 정렬(isort 대체)
# B: bugbear(흔한 버그 패턴), UP: 최신 문법 권장, SIM: 불필요한 복잡도 지적
select = ["E", "F", "I", "B", "UP", "SIM"]
ignore = ["E501"]  # 줄 길이는 ruff format이 관리하므로 중복 경고 제외

[tool.ruff.lint.per-file-ignores]
"tests/*" = ["S101"]  # 테스트 파일에서는 assert 사용을 허용

[tool.mypy]
python_version = "3.11"
strict = true
warn_unused_ignores = true
disallow_untyped_defs = true
exclude = ["tests/"]

flake8은 pyproject.toml을 기본으로 읽지 못합니다(전용 플러그인 없이는 .flake8 파일 또는 setup.cfg의 [flake8] 섹션이 필요). Ruff는 이 제약 없이 pyproject.toml 하나로 동작합니다.

정적 분석이 실제로 잡아내는 문제를 보면 왜 필요한지 체감하기 쉽습니다. 다음은 흔히 무심코 저지르는 두 가지 버그입니다 — 쓰지 않는 임포트와 가변 기본 인자(mutable default argument) 함정입니다.

1
2
3
4
5
6
7

# bad_example.py — 린트 전
import os
import sys  # F401: 사용하지 않는 임포트

def add_item(item, items=[]):  # B006: 가변 기본 인자, 호출 간 상태가 공유됨
    items.append(item)
    return items

ruff check bad_example.py를 실행하면 F401 'sys' imported but unused와 B006 Do not use mutable data structures for argument defaults가 보고됩니다. 수정은 다음과 같습니다.

1
2
3
4
5
6

# good_example.py — 린트 후
def add_item(item: int, items: list[int] | None = None) -> list[int]:
    if items is None:
        items = []
    items.append(item)
    return items

타입 체커는 린터가 잡지 못하는 논리적 타입 불일치를 찾아냅니다. 다음 함수는 실행 자체는 되지만 잘못된 타입으로 호출될 위험이 있습니다.

1
2
3
4

def greet(name: str) -> str:
    return "Hello, " + name

greet(123)  # mypy: Argument 1 to "greet" has incompatible type "int"; expected "str"

mypy는 이 호출을 정적으로 잡아내지만, 타입 힌트 없이 def greet(name):으로만 작성했다면 아무 경고도 내지 못합니다. 즉 mypy의 효용은 타입 힌트를 얼마나 성실히 붙였는가에 정비례합니다.

코드 메트릭

  • 복잡도: McCabe 순환 복잡도
  • 중복도: 코드 중복 측정
  • 커버리지: 테스트 커버리지
  • 기술 부채: 코드 품질 부채
  • 코드 냄새: 리팩토링 신호

자동화 도구

  • pre-commit: 커밋 전 검사
  • tox: 다중 환경 테스트
  • nox: 테스트 자동화
  • GitHub Actions: CI/CD 파이프라인
  • 코드 품질 게이트: 품질 기준 강제

pre-commit은 “커밋 시점”에 검사를 강제해, CI에서야 실패를 발견하는 지연을 없애줍니다. 로컬에서 이미 통과한 코드만 커밋되므로 CI 대기 시간과 리뷰어의 시간 낭비를 함께 줄일 수 있습니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.6.9  # 실제 적용 시 최신 태그로 갱신
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.11.2
    hooks:
      - id: mypy
        additional_dependencies: [types-requests]
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
        args: [--maxkb=500]

설치와 활성화는 pip install pre-commit && pre-commit install 두 줄로 끝나며, 이후 git commit마다 위 훅이 자동 실행됩니다. 훅이 파일을 고친 경우(예: ruff --fix) 첫 커밋 시도는 중단되므로, 변경된 파일을 다시 git add한 뒤 재커밋하는 흐름에 팀이 익숙해져야 합니다.

예시: 최소 품질 게이트(개념)

CI에서 최소한 아래 3가지는 “항상” 돌리는 것이 효과적입니다.

  • 포매팅/린트(빠름)
  • 타입 체크(중간)
  • 테스트(중간~느림)

리팩토링

  • 코드 냄새 식별: 문제 있는 패턴
  • 리팩토링 기법: 구조 개선 방법
  • 안전한 리팩토링: 테스트 기반 개선
  • 점진적 개선: 단계적 품질 향상
  • 레거시 코드: 기존 코드 개선

리팩토링은 “동작을 바꾸지 않고 구조만 개선”하는 작업입니다. 안전하게 하려면 리팩토링 전에 그 동작을 고정하는 테스트가 있어야 하며, 테스트가 없다면 리팩토링은 사실상 재작성이 됩니다. 아래 두 예제는 실무에서 자주 나타나는 냄새인 중복 로직과 깊은 중첩 조건문을 각각 다룹니다.

예제 1: 중복 제거 + 함수 분리. 두 함수가 세율 계산 로직을 그대로 복사해 가지고 있으면, 세율이 바뀔 때 두 곳을 모두 고쳐야 하고 하나를 빠뜨리기 쉽습니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 리팩토링 전
def calculate_order_total(price: float, quantity: int) -> float:
    subtotal = price * quantity
    tax = subtotal * 0.1
    total = subtotal + tax
    print(f"주문 금액: {total:.2f}")
    return total

def calculate_invoice_total(price: float, quantity: int) -> float:
    subtotal = price * quantity
    tax = subtotal * 0.1  # 세율이 바뀌면 이 줄도 함께 고쳐야 함
    total = subtotal + tax
    print(f"청구 금액: {total:.2f}")
    return total

세율 계산을 별도 함수로 뽑아내면 중복이 사라지고, 세율은 한 곳(TAX_RATE)에서만 관리됩니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 리팩토링 후
TAX_RATE = 0.1

def apply_tax(subtotal: float, rate: float = TAX_RATE) -> float:
    return subtotal + subtotal * rate

def calculate_order_total(price: float, quantity: int) -> float:
    total = apply_tax(price * quantity)
    print(f"주문 금액: {total:.2f}")
    return total

def calculate_invoice_total(price: float, quantity: int) -> float:
    total = apply_tax(price * quantity)
    print(f"청구 금액: {total:.2f}")
    return total

예제 2: 이름 개선 + 가드 절(guard clause)로 중첩 축소. 다음 함수는 이름만 봐서는 무슨 일을 하는지 알 수 없고, if가 3단으로 중첩되어 있어 각 분기의 의미를 파악하려면 전체를 다 읽어야 합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 리팩토링 전
def f(u, d):
    if u is not None:
        if u.is_active:
            if d.get("role") == "admin":
                return True
            else:
                return False
        else:
            return False
    else:
        return False

가드 절로 “조건에 맞지 않으면 즉시 반환”하는 형태로 바꾸고, 매개변수와 함수 이름을 의도가 드러나게 바꾸면 로직이 한눈에 들어옵니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 리팩토링 후
class User:
    def __init__(self, is_active: bool) -> None:
        self.is_active = is_active

def is_admin_user(user: User | None, request_data: dict) -> bool:
    if user is None:
        return False
    if not user.is_active:
        return False
    return request_data.get("role") == "admin"

두 예제 모두 동작은 동일하다는 점이 핵심입니다. 리팩토링 전/후 버전에 같은 테스트 스위트를 돌려 통과 여부가 바뀌지 않는지 확인하는 것이 “안전한 리팩토링”의 최소 조건입니다.

기술 부채 관리: 언제 고치고 언제 미룰 것인가

기술 부채는 “당장 편한 선택”과 “장기적으로 저렴한 선택” 사이의 차입입니다. 모든 부채를 즉시 갚으려 하면 신규 기능 개발이 멈추고, 반대로 전혀 갚지 않으면 어느 순간부터 작은 변경조차 비용이 폭증합니다. 실무에서는 아래 기준으로 “지금 갚을 부채”와 “기록해두고 미룰 부채”를 구분합니다.

판단 기준지금 리팩토링미뤄도 되는 경우
변경 빈도최근 몇 주 안에 반복해서 손댄 코드몇 달째 아무도 건드리지 않는 코드
버그 밀도같은 파일에서 버그가 반복 발생배포 이후 이슈가 없었던 코드
테스트 커버리지테스트가 있어 안전망이 확보됨테스트가 없고, 리팩토링보다 테스트 추가가 먼저 필요함
비즈니스 임팩트곧 확장·재사용될 핵심 로직곧 폐기·교체될 예정인 기능
팀 여력지금 건드리는 김에 개선(보이스카우트 규칙)마감이 임박해 범위를 넓히면 위험한 상황

판단이 애매할 때 실무에서 자주 쓰는 원칙은 보이스카우트 규칙(“코드를 처음 봤을 때보다 조금 더 깨끗하게 두고 떠난다”)입니다. 이는 “지금 이 파일을 수정하는 김에, 딱 그 범위 안에서” 작은 개선을 곁들이라는 뜻이지, 관련 없는 파일까지 리팩토링 범위를 넓히라는 뜻은 아닙니다. 반대로 마감이 임박했거나 테스트 커버리지가 없는 코드는 리팩토링을 미루고, 대신 이슈 트래커에 “왜 미루는지”와 “다음에 손댈 조건”을 기록해 부채를 가시화하는 편이 더 안전합니다.

문서화

  • 인라인 문서: 주석과 독스트링
  • API 문서: Sphinx, MkDocs
  • README: 프로젝트 소개
  • CHANGELOG: 변경 이력
  • ADR: 아키텍처 결정 기록

코드 리뷰

  • 리뷰 프로세스: 체크리스트와 절차
  • 피어 리뷰: 동료 검토
  • 자동 리뷰: 도구 기반 검토
  • 리뷰 문화: 건설적 피드백
  • 지식 공유: 팀 학습 촉진

코드 리뷰 체크리스트(핵심)

  • 변경이 요구사항을 만족하는가?
  • 경계/책임이 명확한가? (한 함수/모듈이 너무 많은 일을 하지 않는가?)
  • 오류 처리와 로그는 충분한가?
  • 테스트가 “실패 가능성”을 잡아주는가? (해피패스만 있는가?)
  • 보안/개인정보/비밀키 노출 위험은 없는가?

개발 프로세스

  • 애자일 개발: 반복적 개선
  • DevOps: 개발과 운영 통합
  • 지속적 개선: 카이젠 문화
  • 팀 표준: 공통 규칙 정립
  • 도구 체인: 통합된 개발 환경

자주 하는 실수/주의점

  • 도구를 목표로 삼기: “린트 0개”가 목적이 아니라 “변경 비용 감소”가 목적입니다.
  • 규칙을 한 번에 과하게 도입: 초기에 규칙을 너무 많이 켜면 저항이 커져 유지가 안 됩니다. 단계적으로 강화하세요.
  • 테스트 없는 리팩토링: 테스트가 없으면 리팩토링은 사실상 재작성에 가깝습니다.

실습 프로젝트

프로젝트 1: 로컬 품질 게이트 스크립트

CI를 기다리지 않고 커밋 전에 스스로 품질을 확인할 수 있도록, 여러 정적 분석 도구를 순차 실행하고 결과를 요약하는 스크립트를 작성합니다. 각 검사는 독립적으로 실행되며, 하나라도 실패하면 전체 게이트가 실패로 처리됩니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

# scripts/quality_gate.py
"""로컬/CI에서 품질 게이트를 순차 실행한다."""
from __future__ import annotations

import subprocess
import sys

CHECKS: list[tuple[str, list[str]]] = [
    ("ruff lint", ["ruff", "check", "."]),
    ("ruff format", ["ruff", "format", "--check", "."]),
    ("mypy", ["mypy", "src"]),
    ("pytest", ["pytest", "-q"]),
]


def run_check(name: str, command: list[str]) -> bool:
    print(f"\n=== {name} ===")
    result = subprocess.run(command, capture_output=True, text=True)
    print(result.stdout)
    if result.returncode != 0:
        print(result.stderr, file=sys.stderr)
        print(f"[FAIL] {name}")
        return False
    print(f"[PASS] {name}")
    return True


def main() -> int:
    results = [run_check(name, cmd) for name, cmd in CHECKS]
    if not all(results):
        print("\n품질 게이트 실패: 위 실패 항목을 수정한 뒤 다시 실행하세요.")
        return 1
    print("\n모든 품질 게이트를 통과했습니다.")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

python scripts/quality_gate.py로 실행하며, 이 스크립트 자체를 .pre-commit-config.yaml의 local 훅이나 GitHub Actions 워크플로 한 단계로 그대로 재사용할 수 있습니다. 로컬과 CI가 같은 명령을 실행하므로 “내 컴퓨터에서는 됐는데” 유형의 문제가 줄어듭니다.

프로젝트 2: 레거시 함수 리팩토링과 회귀 테스트

아래는 흔히 보는 “God Function”입니다 — 검증, 할인 계산, 세금 계산, 출력이 한 함수에 뒤섞여 있어 재사용도 단위 테스트도 어렵습니다. 리팩토링 전에 먼저 이 함수의 입출력을 고정하는 테스트를 작성해 회귀를 방지합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# legacy_billing.py — 리팩토링 전
def process_order(name, price, qty, discount_code):
    if price <= 0 or qty <= 0:
        print("잘못된 입력")
        return None
    subtotal = price * qty
    if discount_code == "VIP":
        subtotal = subtotal * 0.8
    elif discount_code == "MEMBER":
        subtotal = subtotal * 0.9
    tax = subtotal * 0.1
    total = subtotal + tax
    print(f"{name}님의 결제 금액: {total:.2f}")
    return total

검증, 할인 정책, 세금 계산이라는 책임을 각각 함수로 분리하고, 매직 문자열("VIP", "MEMBER")은 명시적인 매핑으로 바꿉니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

# billing.py — 리팩토링 후
from __future__ import annotations

from dataclasses import dataclass

DISCOUNT_RATES: dict[str, float] = {"VIP": 0.2, "MEMBER": 0.1}
TAX_RATE = 0.1


@dataclass
class Order:
    customer_name: str
    unit_price: float
    quantity: int
    discount_code: str | None = None


def validate_order(order: Order) -> None:
    if order.unit_price <= 0 or order.quantity <= 0:
        raise ValueError("가격과 수량은 0보다 커야 합니다")


def apply_discount(subtotal: float, discount_code: str | None) -> float:
    if discount_code is None:
        return subtotal
    rate = DISCOUNT_RATES.get(discount_code, 0.0)
    return subtotal * (1 - rate)


def apply_tax(subtotal: float, rate: float = TAX_RATE) -> float:
    return subtotal + subtotal * rate


def calculate_total(order: Order) -> float:
    validate_order(order)
    subtotal = order.unit_price * order.quantity
    discounted = apply_discount(subtotal, order.discount_code)
    return apply_tax(discounted)

리팩토링이 기존 동작을 그대로 보존하는지는 실행 결과를 비교하는 회귀 테스트로 확인합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# test_billing.py
import pytest
from billing import Order, calculate_total

def test_no_discount():
    order = Order("Alice", 1000, 2, None)
    assert calculate_total(order) == pytest.approx(2200.0)

def test_vip_discount():
    order = Order("Bob", 1000, 2, "VIP")
    # subtotal=2000 -> VIP 20% 할인=1600 -> 세금 10%=1760
    assert calculate_total(order) == pytest.approx(1760.0)

def test_invalid_quantity_raises():
    order = Order("Carol", 1000, 0, None)
    with pytest.raises(ValueError):
        calculate_total(order)

validate_order가 예외를 발생시키도록 바꾼 점은 원본과의 유일한 동작 차이입니다(원본은 print 후 None을 반환). 이런 의도적 변경은 리팩토링과 별도로 커밋 메시지에 명시해, “동작 보존”과 “동작 변경”을 리뷰어가 구분할 수 있게 합니다.

체크리스트

  • 코딩 표준 적용
  • 정적 분석 도구 활용
  • 자동화 파이프라인 구축
  • 리팩토링 기법 적용
  • 문서화 습관 형성

다음 단계

코드 품질 관리를 마스터했다면, 파이썬의 고급 주제들과 최신 동향을 학습합니다.

[Python Master] 파이썬 마스터 커리큘럼의 관련 글들

📚 [Python Master] 파이썬 마스터 커리큘럼 전체 보기 (31개)

Related Content