5장 생성 코드 읽기 I: 코드를 말로 설명하기

5.1 코드를 말로 설명한다는 것: EiPE

1주차의 역할 분담을 다시 꺼내자. 코드는 AI가 쓰고, 학생은 문제 분해·생성 코드 읽기·화학공학적 검증을 책임진다. 이 분담에서 "읽기"는 채점 대상이다. 최종 시험 루브릭의 코드 이해 10점은 무작위 지목 설명 4점, "이 줄을 바꾸면?" 예측 3점, 한계·개선점 3점으로 구성되고, 지목 질문 3개 중 2개 이상 설명에 실패하면 이 차원 전체가 0점이다.

코드 한 조각의 목적과 동작을 자연어로 설명하는 훈련을 EiPE(Explain in Plain English)라 한다. 컴퓨팅 교육 연구에서 코드 이해도를 측정하는 표준 문항 유형으로 쓰여 왔고, 이 수업에서는 시험1의 서술 문항과 매주 구술의 공통 형식이다. 프로그래밍 초보자가 LLM이 생성한 코드를 올바르게 이해하는 비율이 32.5%에 그쳤다는 보고(arXiv 2504.19037)가 있다. 셋 중 둘은 돌아가는 코드를 설명하지 못한 채 제출한다는 뜻이다.

5.1.1 라인 낭독과 설명은 다르다

다음 함수를 보자. mmHg 단위의 압력을 bar로 바꾸는, AI가 생성했을 법한 네 줄짜리 코드다.

def mmhg_to_bar(p_mmhg):
    """mmHg 단위 압력을 bar로 환산한다."""
    p_pa = p_mmhg * 133.322   # 압력 [Pa], 1 mmHg = 133.322 Pa
    return p_pa / 1.0e5       # 압력 [bar], 1 bar = 1e5 Pa

이 코드에 대한 두 가지 설명을 비교해 보자.

나쁜 설명(라인 낭독): "p_mmhg에 133.322를 곱해서 p_pa에 넣고, p_pa를 1.0e5로 나눠서 반환한다."

좋은 설명(EiPE): "mmHg 단위의 압력을 받아 bar 단위로 바꿔 돌려주는 함수다. 중간에 Pa를 한 번 거쳐 두 단계로 환산한다. 음수 압력 같은 비물리적 입력은 걸러내지 않는다."

나쁜 설명은 코드를 소리 내어 읽었을 뿐이어서, 코드를 보지 않은 사람에게는 정보를 거의 주지 못한다. 좋은 설명은 코드 없이도 이 함수를 다시 만들 수 있을 만큼의 정보를 담는다. 무엇을 받아 무엇을 돌려주는지, 어떤 경로로 바꾸는지, 어떤 한계를 안고 있는지가 여기에 들어간다. 시험1의 EiPE 문항과 구술 평가의 지목 질문이 요구하는 것은 후자다.

좋은 설명에는 뼈대가 있다. 목적("무엇을 하는 함수인가"), 입력("무엇을, 어떤 단위로 받는가"), 처리("어떤 경로로 바꾸는가"), 출력("무엇을, 어떤 단위로 돌려주는가"), 한계("어떤 입력에서 무너지는가")의 다섯 요소다. 다섯 요소를 전부 갖추면 두세 문장이 된다. 이 공식은 장 끝의 요약에 S 5-1로 다시 나온다.

읽기가 쓰기보다 먼저인 이유는 이 수업의 구조 자체에 있다. 쓰기는 AI가 대신하지만, AI가 쓴 것이 맞는지 판정하는 읽기는 사람의 몫으로 남는다. 프로그래밍 문법을 다 배운 뒤에 읽기를 시작하지 않고, 읽기에 필요한 최소 문법(변수, 제어문, 함수)만을 이번 장에서 골라 배운다.

5.2 변수 읽기: 이름, 값, 그리고 단위

값을 가리키는 이름을 변수(variable)라 한다. 코드를 읽는 일은 결국 각 변수가 어느 시점에 어떤 값을 가리키는지 따라가는 일이다. 아래 네 줄을 보자.

p_mmhg = 800.0                 # 측정 압력 [mmHg]
PA_PER_MMHG = 133.322          # 환산계수 [Pa/mmHg]
p_pa = p_mmhg * PA_PER_MMHG    # 압력 [Pa]
p_bar = p_pa / 1.0e5           # 압력 [bar], 1 bar = 1e5 Pa
print(f"{p_bar:.4f} bar")      # 출력: 1.0666 bar

첫 줄은 p_mmhg라는 이름에 800.0이라는 값을 묶는다. 이런 문장을 할당(assignment)이라 한다. 둘째 줄의 PA_PER_MMHG는 환산계수를 담은 변수인데, 대문자 이름은 "이 값은 바꾸지 않겠다"는 관례적 신호다. 셋째 줄에서 곱셈이 일어나 새 변수 p_pa가 생기고, 넷째 줄에서 다시 p_bar가 생긴다.

실행 순서를 따라 변수의 값을 표로 적는 일을 상태 추적(tracing)이라 한다. 위 코드의 상태표는 다음과 같다.

화공 코드의 변수에는 프로그래밍 교재에 없는 규율이 하나 더 붙는다. 물리량 변수에는 반드시 단위 주석을 단다는 규율이다. p = 800.0이라고만 적힌 코드에서 800이 mmHg인지 kPa인지 psi인지는 코드 어디에도 없다. 단위가 주석에 있어야 검증 루틴의 첫 항목인 단위 체크가 가능해진다.

단위를 추적하면 코드가 틀린 것도 잡아낸다. 단위환산 교재의 고전적 실수 사례를 코드로 옮겨 보자.

p_mmhg = 800.0                    # 압력 [mmHg]
p_wrong = p_mmhg * 760.0 / 1.013  # 잘못된 환산: 단위가 [mmHg²/bar]가 된다
print(p_wrong)                    # 600197.4... — 비물리적 크기

환산계수 "1 atm = 760 mmHg = 1.013 bar"를 거꾸로 곱하면 값이 6.0×10⁵라는 터무니없는 크기가 되고, 단위는 mmHg²/bar라는 존재하지 않는 조합이 된다. 값을 보고 이상함을 느끼는 것이 극한값 감각이고, 단위를 적어 보고 오류를 확정하는 것이 단위 체크다. 3장에서 도입한 검증 루틴 3종이 코드 읽기에서 그대로 작동한다.

t_f = 212.0                # 온도 [°F]
t_c = (t_f - 32.0) * 5 / 9 # 온도 [°C]
t_k = t_c + 273.15         # 온도 [K]
print(f"{t_k} K")

5.3 제어문 읽기: 갈림길과 반복

지금까지의 코드는 위에서 아래로 한 번씩만 실행됐다. 그러나 실제 코드는 "이 조건이 참이면 이것을 하고, 아니면 저것을 하라", "이 목록의 항목마다 같은 일을 반복하라" 같은 문장으로 흐름을 바꾼다. 조건에 따라 실행 경로를 가르는 문장을 조건문(conditional statement)이라 하고, 같은 블록을 여러 번 실행시키는 문장을 반복문(loop)이라 한다.

화공 도구에서 조건문의 첫 임무는 유효범위 검사다. 물성 상관식의 상수에는 반드시 유효 온도범위가 붙어 있고, 범위 밖의 온도로 값을 구하는 일을 외삽(extrapolation)이라 한다. 외삽을 조용히 허용하는 코드는 위험하므로, 좋은 도구는 계산 전에 범위를 검사한다.

t = 298.15                    # 조회 온도 [K]
t_min, t_max = 379.0, 573.0   # 상수 유효범위 [K], NIST(Liu and Lindsay)
if t < t_min or t > t_max:
    print("경고: 유효범위 밖 — 외삽 결과는 신뢰할 수 없다")
else:
    print("유효범위 안")

if 다음의 t < t_min or t > t_max는 참 또는 거짓으로 계산되는 식이다. 참이면 바로 아래 들여쓰인 블록이 실행되고, 거짓이면 else 블록이 실행된다. 여기서는 298.15가 379보다 작으므로 조건이 참이 되어 경고가 출력된다. 들여쓰기가 곧 소속을 나타낸다. 어떤 줄이 어느 블록에 속하는지는 들여쓰기 깊이가 결정한다.

반복문은 같은 계산을 목록 전체에 적용한다. 여러 값을 순서대로 담는 자료형을 리스트(list)라 하며, 대괄호로 만든다.

pressures_psi = [10.0, 14.7, 30.0, 100.0]  # 압력 목록 [psi]
KPA_PER_PSI = 6.895                         # 환산계수 [kPa/psi]
for p in pressures_psi:
    print(f"{p:6.1f} psi = {p * KPA_PER_PSI:8.1f} kPa")

for p in pressures_psi:는 리스트의 항목을 하나씩 꺼내 p에 담고, 들여쓰인 블록을 항목 수만큼(여기서는 네 번) 실행한다. 둘째 항목 14.7 psi는 101.4 kPa로 환산되는데, 이는 1 atm(101.325 kPa)과 거의 같다. 표 하나를 출력했을 뿐인데 대조값 검증이 공짜로 따라온 셈이다.

실행 흐름을 읽는 요령은 "다음에 실행될 줄이 몇 번째 줄인가"를 계속 자문하는 것이다. 조건문에서는 어느 가지로 가는지, 반복문에서는 몇 바퀴째인지를 상태표 옆에 함께 적으면 된다. 흐름 추적은 유용하지만 코드가 길어지면 금세 벅차진다. 그때 필요한 것이 다음 절의 함수 단위 읽기다.

t = 320.0   # 조회 온도 [K]
# 물의 Antoine 상수 (log10, p*[bar], T[K]) — 표 5-2, NIST WebBook
if 273.0 <= t <= 303.0:
    a, b, c = 5.40221, 1838.675, -31.737
elif 304.0 <= t <= 333.0:
    a, b, c = 5.20389, 1733.926, -39.485
elif 334.0 <= t <= 363.0:
    a, b, c = 5.07680, 1659.793, -45.854
else:
    raise ValueError("유효범위 밖 온도")
p_bar = 10 ** (a - b / (t + c))   # 증기압 [bar]
print(f"{p_bar:.3f} bar")

표 5-2에는 이 교재의 상수 표기 의무 네 가지(로그 밑, 압력 단위, 온도 단위, 유효범위)가 전부 들어 있다. 넷 중 하나라도 빠진 상수 표는 쓰지 않는다. 마지막 행의 상수를 유효범위 아래인 373 K에 적용하면 0.76 bar가 나오는데, 물이 1 atm(1.013 bar)에서 끓는다는 상식과 25% 어긋난다. 외삽의 대가는 8장에서 정량적으로 다룬다.

5.4 함수 읽기: 입력·변환·출력의 계약

이름을 붙여 두고 필요할 때마다 불러 쓰는 코드 묶음을 함수(function)라 한다. 함수에 넘겨주는 값을 인자(argument), 함수가 돌려주는 값을 반환값(return value)이라 한다. 함수의 첫 줄(이름과 인자 목록)은 "무엇을 주면 무엇을 돌려주겠다"는 계약서이고, 함수 읽기는 이 계약서 읽기에서 시작한다.

def mmhg_to_bar(p_mmhg):이라는 첫 줄만 보고도 세 가지를 읽어낼 수 있다. mmHg를 bar로 바꾸는 일을 하고, 압력 하나를 받으며, 이름의 방향(mmhg→bar)이 환산 방향을 약속한다. 본문을 읽기 전에 계약부터 읽는 습관은 코드가 길어질수록 도움이 된다. 흐름 추적이 벅찬 큰 코드도 함수 단위로 끊으면 계약들의 연결로 읽힌다.

실제로 AI에게 함수를 시키고 그 결과를 읽어 보자. 프롬프트-응답 리스팅의 3단 형식은 2장에서 선언한 그대로다.

def psi_to_kpa(p_psi):
    """psi 단위 압력을 kPa로 환산한다."""
    KPA_PER_PSI = 6.895          # 환산계수 [kPa/psi]
    return p_psi * KPA_PER_PSI   # 압력 [kPa]

검증 코멘트가 짚은 대로, 생성된 함수는 계약을 지키지만 비물리적 입력에 침묵한다. "절대압이 음수면 ValueError를 일으켜 줘"라고 한 줄 더 요구하면 5.3절의 조건문이 함수 안으로 들어온다. 프롬프트 → 읽기 → 결함 발견 → 프롬프트 개선의 사이클이 한 바퀴 돈 것이다.

5.4.1 딕셔너리: 이름으로 값을 꺼내는 상자

물성 조회기는 밀도·끓는점처럼 여러 값을 한꺼번에 다룬다. 이름표(키)로 값을 꺼내는 자료형을 딕셔너리(dictionary)라 하며, 중괄호로 만든다.

props = {"T_boil_K": 373.12, "rho_kg_m3": 997.0}  # 물성 이름 → 값
print(props["T_boil_K"])   # 키로 조회: 373.12

리스트가 순서(0번째, 1번째)로 값을 꺼낸다면 딕셔너리는 이름으로 꺼낸다. props["rho_kg_m3"]처럼 키에 단위를 새겨 두는 것도 단위 주석 규율의 연장이다. 이 장에서 리스트와 딕셔너리는 여기까지만 필요하다. 항목을 담고, 꺼내고, 반복문으로 순회하는 수준이면 도구④를 읽고 만들 수 있다.

5.4.2 CoolProp: 물성을 조회하는 함수 라이브러리

물성값 자체를 AI에게 묻는 것은 위험하다는 사실을 3장에서 보았다. 대안은 검증된 물성 라이브러리를 코드로 조회하는 것이다. CoolProp은 순수 유체의 열역학 물성을 계산해 주는 오픈소스 라이브러리로, PropsSI 함수 하나로 대부분의 조회가 끝난다.

from CoolProp.CoolProp import PropsSI

def water_boiling_t(p_pa):
    """압력 p_pa[Pa]에서 물의 끓는점[K]을 반환한다."""
    return PropsSI("T", "P", p_pa, "Q", 0, "Water")  # 포화온도 [K]

t_b = water_boiling_t(101325.0)   # 1 atm = 101325 Pa
print(f"{t_b:.2f} K")             # 출력: 373.12 K

5.5 첫 타이머, 첫 공개 구술: 마음의 준비

이번 주 실습부터 두 가지가 바뀐다. 첫째, 과제에 30분의 제한시간이 걸린다. 둘째, 실습 마무리에 무작위로 지목된 학생이 자기 코드 한 부분을 모두 앞에서 1분간 설명한다. 1~4주의 실습이 시간 무제한에 페어 안에서만 설명하는 저부담 구간이었다면, 5주차는 시험 형식으로 넘어가는 첫 계단이다.

제한시간은 1장에서 안내한 대로 최종 시험의 120분까지 매주 조금씩 늘어난다. 처음부터 2시간짜리 압박을 주는 대신 시간 감각을 단계적으로 키우는 설계다. 30분 안에 도구④를 완성하지 못해도 성적에는 아무 일도 일어나지 않는다. 이번 주 결과는 등수 없이 통과/재도전의 2단계로만 처리되고, 재도전은 다음 실습 전까지 열려 있다.

공개 구술이 두려운 것은 정상이다. 다만 이 장치의 정체를 알면 부담이 줄어든다. 구술은 4장에서 배운 인출연습의 사회적 버전이다. 머릿속에 있다고 믿는 지식을 꺼내 보는 행위 자체가 기억을 강화하며, 설명하다 막히는 지점이 곧 공부할 지점이다. 지금 사람들 앞에서 막히는 데에는 아무 대가가 없지만, 최종 시험의 구술 방어에서 막히면 점수로 이어진다. 매주 반복되는 리허설이 그 부담을 미리 덜어 준다.

준비 방법은 단순하다. 실습 중 함수 하나를 완성할 때마다 소리 내지 않아도 좋으니 S 5-1의 순서(목적→입력→처리→출력→한계)로 속으로 한 번 설명해 본다. 퇴실 전 페어에게 1분 설명을 한 번 하고 나가면 그 주의 구술 리허설은 끝난 셈이다. 막히면 침묵하지 말고 "목적부터 다시 말하겠습니다"라고 처음으로 돌아가면 된다. 구조를 따라 말하는 훈련이다.