디버깅의 기술: 추측 대신 증거로

버그를 빨리 잡는 사람은 운이 좋은 게 아니라 증거를 모으는 순서를 알아요. 오류 메시지와 트레이스백을 아래에서 위로 읽는 법, 버그를 확실하게 다시 일으키고 범위를 반씩 줄여 1,000건 중 문제 하나를 10번 만에 찾는 법, print 대신 로그를 쓰는 이유, 디버거와 git bisect를 익히고, 부동소수점, 함수 기본값으로 쓴 목록, 한글 인코딩, 상대 경로처럼 자주 만나는 버그들을 직접 재현해 봐요.

초급강의 3 / 6약 12분

코드는 우리가 쓴 대로 움직이지, 원한 대로 움직이지 않아요. 그 차이가 버그예요. 버그를 잡는 일, 디버깅은 프로그래밍 시간의 큰 부분을 차지해요. 그런데 디버깅을 잘하는 사람과 못하는 사람의 차이는 지식보다 방법에 있어요.

못하는 사람은 추측해요. "아마 이거 때문일 거야" 하고 코드를 고치고, 안 되면 또 다른 곳을 고쳐요. 운이 좋으면 금방 잡지만, 대부분은 이것저것 바꾸다 원래 문제에 새 문제까지 얹어요. 잘하는 사람은 증거를 모아요. 무슨 일이 일어나는지 관찰하고, 가설을 세우고, 가설을 확인하는 실험을 해요. 과학자가 일하는 방식 그대로예요.

1단계: 오류 메시지를 끝까지 읽기

놀랍게도 많은 버그는 오류 메시지에 답이 적혀 있어요. 학생들의 평균 점수를 출력하는 프로그램이 멈췄어요.

# report.py
def average(scores):
    return sum(scores) / len(scores)

def report(students):
    for name, scores in students.items():
        print(name, average(scores))

students = {"민지": [90, 85], "도윤": []}
report(students)
민지 87.5
Traceback (most recent call last):
  File "report.py", line 10, in <module>
    report(students)
    ~~~~~~^^^^^^^^^^
  File "report.py", line 7, in report
    print(name, average(scores))
                ~~~~~~~^^^^^^^^
  File "report.py", line 3, in average
    return sum(scores) / len(scores)
           ~~~~~~~~~~~~^~~~~~~~~~~~~
ZeroDivisionError: division by zero

이 출력을 트레이스백이라고 불러요. 오류가 났을 때 함수들이 어떤 순서로 불렸는지 보여 주는 기록이에요. 읽는 순서가 있어요.

  1. 맨 아래 줄부터: ZeroDivisionError: division by zero. 오류의 종류와 내용이에요. 0으로 나눴대요.
  2. 바로 위: 오류가 난 곳이에요. report.py의 3번째 줄, average 함수 안의 sum(scores) / len(scores). 물결과 꺾쇠 표시(~, ^)는 그 줄에서 정확히 어느 부분인지 가리켜요. 나눗셈 기호에 ^가 있죠(파이썬 버전에 따라 이 표시는 없을 수 있어요).
  3. 위로 올라가며: 누가 그 함수를 불렀는지 따라가요. report의 7번째 줄이 average(scores)를 불렀고, 그건 10번째 줄의 report(students)가 불렀어요.

len(scores)가 0이 되는 경우는 점수 목록이 비었을 때예요. 그리고 출력에 "민지 87.5"는 나왔으니, 문제는 두 번째 학생인 도윤이에요. 도윤의 점수가 []이에요. 원인을 찾았어요. 고치기 전에 어떻게 고칠지 정해야 해요. 점수가 없는 학생은 평균을 0으로 볼까요, "없음"으로 볼까요? 0점과 시험을 안 본 것은 다르니 "없음"이 맞아 보여요.

def average(scores):
    if not scores:                                   # 점수가 없으면 평균도 없어요
        return None
    return sum(scores) / len(scores)

assert average([90, 85]) == 87.5
assert average([]) is None                           # 방금 잡은 버그가 다시 생기지 않게
print("통과")
통과

고친 뒤에 버그를 일으켰던 경우를 시험으로 남겨요(assert average([]) is None). 나중에 누군가 코드를 고치다 같은 버그를 다시 만들면 바로 알 수 있어요.

2단계: 버그를 확실하게 다시 일으키기

다시 일으킬 수 없는 버그는 고쳤는지도 확인할 수 없어요. 그래서 디버깅의 첫 목표는 버그를 마음대로 재현하는 것이에요.

  • 조건을 기록해요: 어떤 입력에서, 어떤 순서로 했을 때, 어떤 환경(운영체제, 파이썬 버전, 라이브러리 버전)에서 생기나요?
  • 가끔만 생기는 버그는 무작위성, 시간, 동시에 도는 작업, 네트워크처럼 매번 달라지는 요소를 의심해요. 무작위 씨앗을 고정하거나 시간을 흉내 내서 고정해요.
  • 줄여요: 버그가 나는 코드에서 상관없는 부분을 하나씩 지워 가며, 버그가 여전히 나는 가장 작은 코드를 만들어요. 이 과정에서 원인이 저절로 드러나는 경우가 많고, 남에게 도움을 청할 때도 이 작은 코드가 필요해요(다음 강의).

3단계: 범위를 반씩 줄이기

어디서 문제가 생기는지 모를 때 가장 강력한 방법은 반으로 나누기예요. 주문 기록 1,000개를 처리하다 어디선가 오류가 나는데, 어느 기록인지 모른다고 해 볼게요. 하나씩 확인하면 최악의 경우 1,000번이지만, 반으로 나눠 앞쪽 절반이 멀쩡한지 확인하는 걸 되풀이하면 훨씬 빨라요.

def process(record):
    return 100 / record["qty"]

records = [{"id": i, "qty": (i % 7) + 1} for i in range(1000)]
records[637]["qty"] = 0                              # 1,000개 중 하나가 문제예요

def first_bad(items, fn):
    lo, hi, steps = 0, len(items), 0
    while hi - lo > 1:                               # 범위가 하나로 좁혀질 때까지
        steps += 1
        mid = (lo + hi) // 2
        try:
            for x in items[lo:mid]:
                fn(x)
            lo = mid                                 # 앞 절반은 멀쩡해요: 뒤 절반에 있어요
        except Exception:
            hi = mid                                 # 앞 절반에 있어요
    return lo, steps

print(first_bad(records, process))
(637, 10)

10번 만에 637번 기록을 찾았어요. 210=10242^{10} = 1024라서, 1,000개라도 10번이면 충분해요. 알고리즘 트랙의 이진 탐색과 같은 원리예요. 이 방법은 데이터뿐 아니라 어디에나 쓸 수 있어요.

  • 코드: 의심 가는 코드의 절반을 잠시 꺼 보고 버그가 사라지는지 봐요.
  • 기록: "어제까지는 됐는데 오늘 안 돼요"라면 Git의 기록이 증거예요. git bisect는 잘 되던 커밋과 안 되는 커밋 사이를 반씩 나눠 가며, 버그를 처음 만든 커밋을 찾아 줘요.
git bisect start
git bisect bad                  # 지금은 안 돼요
git bisect good a1b2c3d         # 이 커밋에서는 됐어요
# Git이 가운데 커밋으로 옮겨 주면, 시험해 보고 결과를 알려 줘요
git bisect good                 # 또는 git bisect bad
# ...반복하면 "처음으로 나빠진 커밋"을 알려 줘요
git bisect reset                # 원래 자리로 돌아가기

4단계: 관찰하기(print, 로그, 디버거)

가설을 확인하려면 프로그램 안을 들여다봐야 해요.

print는 가장 쉬운 방법이에요. 의심 가는 곳에서 변수 값을 찍어 봐요. 다만 다 고친 뒤에 지우는 걸 잊기 쉽고, 무엇이 언제 찍혔는지 구분하기 어려워요.

로그는 print를 체계적으로 만든 거예요. 메시지마다 중요도(수준)를 붙이고, 설정 한 줄로 어느 수준부터 보일지 정해요.

import logging
import sys

logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s", stream=sys.stdout)
log = logging.getLogger("report")

def average(scores):
    log.debug("받은 점수: %s", scores)              # 자세한 정보: 평소에는 숨겨요
    if not scores:
        log.warning("점수가 비어 있어요")            # 주의가 필요한 일
        return None
    return sum(scores) / len(scores)

average([90, 85])
average([])
WARNING 점수가 비어 있어요

수준은 보통 DEBUG(자세한 정보), INFO(일반적인 진행), WARNING(주의), ERROR(실패), CRITICAL(심각) 순이에요. INFO로 설정했더니 DEBUG 메시지는 숨고 WARNING만 보였어요. 문제를 조사할 때만 DEBUG로 바꿔 자세히 보면 돼요. 서버에서 돌아가는 프로그램이라면 로그를 파일로 남겨서, 문제가 생긴 뒤에 무슨 일이 있었는지 볼 수 있어요.

디버거는 프로그램을 원하는 곳에서 멈춰 놓고, 그 순간의 변수를 살펴보고, 한 줄씩 실행해 보게 해 줘요. 파이썬에서는 코드에 breakpoint()를 넣으면 그 자리에서 멈춰요. 멈춘 상태에서 쓰는 명령은 이래요.

명령뜻
p 변수변수 값 보기
n다음 줄 실행 (함수 안으로 들어가지 않음)
s다음 줄 실행 (함수 안으로 들어감)
c다음 멈춤 지점까지 계속 실행
q끝내기

VS Code 같은 편집기에서는 줄 번호 옆을 눌러 멈춤 지점을 찍고, 화면에서 변수를 보며 같은 일을 할 수 있어요. 반복문 안에서 특정 조건일 때만 멈추는 조건부 멈춤 지점도 쓸 수 있어요.

5단계: 말로 설명해 보기

막혔을 때 코드를 한 줄씩 소리 내어 설명해 보세요. 동료든, 책상 위의 고무 오리든 상관없어요. "이 줄은 점수 목록을 받아서... 어, 목록이 비면?" 설명하다 보면 머릿속에서 건너뛰었던 가정이 드러나요. 개발자들 사이에서 고무 오리 디버깅이라고 불리는 유명한 방법이에요. AI에게 설명하는 것도 같은 효과가 있어요.

자주 만나는 버그들

처음 만나면 당황하지만, 한 번 보면 다음부터는 바로 알아보는 버그들이에요.

import math

print(0.1 + 0.2 == 0.3, 0.1 + 0.2, math.isclose(0.1 + 0.2, 0.3))

def add_item(item, items=[]):                        # 기본값 목록이 함수에 하나뿐이에요
    items.append(item)
    return items
print(add_item("사과"), add_item("배"))

def add_item_fixed(item, items=None):
    if items is None:
        items = []                                   # 부를 때마다 새 목록
    items.append(item)
    return items
print(add_item_fixed("사과"), add_item_fixed("배"))

print(list(range(1, 5)), len(range(1, 5)))
print("3" + "4", int("3") + int("4"))

data = "안녕하세요".encode("utf-8")
print(data.decode("cp949", errors="replace"))       # 다른 인코딩으로 읽으면
try:
    data.decode("cp949")
except UnicodeDecodeError as e:
    print(type(e).__name__, e.reason)
print(data.decode("utf-8"))
False 0.30000000000000004 True
['사과', '배'] ['사과', '배']
['사과'] ['배']
[1, 2, 3, 4] 4
34 7
�븞�뀞�븯�꽭�슂
UnicodeDecodeError illegal multibyte sequence
안녕하세요
  • 부동소수점: 컴퓨터는 0.1을 2진수로 정확히 담을 수 없어서 0.1 + 0.2가 0.30000000000000004가 돼요. 실수는 ==로 비교하지 말고 math.isclose처럼 오차를 허용해서 비교해요. 돈 계산은 원 단위 정수나 decimal을 써요.
  • 기본값으로 쓴 목록: 함수의 기본값은 함수를 만들 때 한 번만 만들어져요. 그래서 add_item을 부를 때마다 같은 목록에 쌓여서, 두 번째 호출에 사과가 섞여 나왔어요. 기본값은 None으로 두고 함수 안에서 새로 만들어요.
  • 하나 차이: range(1, 5)는 1부터 4까지예요. 끝은 포함하지 않아요. 반복 횟수가 하나 많거나 적은 버그가 정말 흔해요.
  • 글자와 숫자: input()이나 파일에서 읽은 값은 숫자처럼 보여도 글자예요. "3" + "4"는 "34"가 돼요. 계산 전에 int()로 바꿔요.
  • 한글 인코딩: UTF-8로 저장된 한글을 다른 방식(예전 윈도의 cp949)으로 읽으면 글자가 깨지거나 오류가 나요. 한국어 윈도에서 파이썬의 open()은 설정에 따라 기본으로 cp949를 쓸 수 있어서, 파일을 열 때는 open(경로, encoding="utf-8")처럼 인코딩을 꼭 적어요. 컴퓨터 기초 트랙의 문자 인코딩 강의에서 자세히 다뤄요.

글자가 아닌 곳에서 생기는 버그도 있어요.

  • 상대 경로: open("data.txt")는 프로그램 파일이 있는 폴더가 아니라 실행한 위치(현재 작업 폴더)에서 파일을 찾아요. 다른 폴더에서 실행하면 "파일이 없다"는 오류가 나요. pathlib.Path(__file__).parent / "data.txt"처럼 코드 파일 기준으로 경로를 만들어요.
  • 엉뚱한 환경: 라이브러리를 설치했는데 "모듈이 없다"고 나오면, 설치한 파이썬과 실행한 파이썬이 다른 경우가 많아요. python -m pip install처럼 실행할 파이썬으로 설치하고, 가상 환경을 켰는지 확인해요.
  • 캐시: 고쳤는데 그대로라면, 브라우저나 프로그램이 옛 결과를 저장해 두고 보여 주는 건 아닌지 의심해요.

고친 다음에 할 일

  1. 버그를 재현하는 시험을 남겨요. 고치기 전에는 실패하고, 고친 뒤에는 통과하는 시험이에요.
  2. 비슷한 곳을 찾아봐요. 같은 실수를 다른 곳에서도 했을 수 있어요.
  3. 원인을 기록해요. 커밋 메시지에 "무엇이 왜 문제였고 어떻게 고쳤는지" 남겨요.
  4. 증상이 아니라 원인을 고쳤는지 확인해요. 오류가 나는 줄을 try로 감싸서 오류를 숨기는 건 고친 게 아니에요. 문제가 나중에 더 찾기 어려운 곳에서 터져요.

실습

  1. report.py를 고치지 않은 채로, 출력이 "민지 87.5"까지 나왔다는 점만으로 문제가 어느 학생인지 알 수 있는 이유를 설명해 보세요.
  2. first_bad에서 문제가 되는 기록이 두 개라면 어떤 기록을 찾나요? 실험해 보세요.
  3. 로그 수준을 DEBUG로 바꿔 보세요. 무엇이 더 보이나요?
  4. 짧은 코드에 breakpoint()를 넣고 p, n, c를 써 보세요.
  5. 최근에 만난 버그 하나를 떠올려, "관찰한 것, 세운 가설, 확인한 실험, 원인"을 네 줄로 적어 보세요.

자주 하는 실수

  • 오류 메시지를 안 읽고 검색부터 하기. 답의 절반은 메시지에 있어요.
  • 추측으로 여러 곳을 한꺼번에 고치기. 무엇이 고쳤는지, 무엇이 새 문제를 만들었는지 알 수 없어요. 한 번에 하나만 바꿔요.
  • 재현하지 않고 고쳤다고 믿기. 버그가 나던 조건에서 다시 확인해요.
  • 오류를 try로 덮기. 증상만 숨기고 원인은 남아요.
  • "내 코드는 맞는데 라이브러리가 이상해요." 가능하지만 드물어요. 내 코드부터 의심해요.

점검 문제

  1. 트레이스백은 어느 줄부터 읽나요? 그 줄에는 무엇이 있나요?
  2. 버그를 고치기 전에 먼저 해야 할 일은?
  3. 1,000개 중 문제가 되는 것 하나를 반씩 나누기로 찾으면 대략 몇 번이면 되나요? 이유는?
  4. print 대신 로그를 쓰면 좋은 점 두 가지는?
  5. 0.1 + 0.2 == 0.3이 False인 이유와 올바른 비교 방법은?
  6. 함수의 기본값으로 빈 목록을 쓰면 안 되는 이유는?
  7. 한글 파일을 읽을 때 글자가 깨지면 무엇을 의심해야 하나요?

정답

  1. 맨 아래 줄부터 읽어요. 오류의 종류와 내용이 있어요. 바로 위가 오류가 난 곳이고, 위로 올라가며 누가 불렀는지 따라가요.
  2. 버그를 확실하게 다시 일으킬 수 있게 만드는 거예요. 재현할 수 없으면 고쳤는지도 확인할 수 없어요.
  3. 약 10번이에요. 한 번 나눌 때마다 범위가 절반이 되고, 210=10242^{10} = 1024가 1,000보다 크기 때문이에요.
  4. 중요도 수준으로 보일 메시지를 설정 한 줄로 조절할 수 있고, 파일로 남겨 문제가 생긴 뒤에 볼 수 있어요.
  5. 0.1과 0.2를 2진수로 정확히 담을 수 없어 작은 오차가 생기기 때문이에요. math.isclose처럼 오차를 허용해서 비교해요.
  6. 기본값은 함수를 만들 때 한 번만 만들어져서, 호출할 때마다 같은 목록을 함께 쓰게 되기 때문이에요.
  7. 저장할 때와 읽을 때의 인코딩이 다른지 의심해요. 파일을 열 때 encoding="utf-8"처럼 명시해요.

다음 강의

혼자 힘으로 안 풀릴 때도 있어요. 다음 강의에서는 공식 문서에서 답을 찾는 법, 그리고 남에게(사람이든 AI든) 좋은 질문을 하는 법을 다뤄요. 오늘 만든 "가장 작은 재현 코드"가 좋은 질문의 핵심 재료가 돼요.