읽기 쉬운 코드의 조건

코드는 쓰는 시간보다 읽히는 시간이 훨씬 길어요. 이름만 봐도 뜻이 보이게 짓기, 한 가지 일만 하는 작은 함수, 중첩을 줄이는 이른 반환, 숫자 대신 이름 붙인 상수, 무엇이 아니라 왜를 적는 주석을 익히고, 초보자가 흔히 쓰는 주문 금액 계산 함수를 한 단계씩 고치면서 시험으로 결과가 똑같은지 확인해요. 동작을 지키는 정리와 동작을 바꾸는 수정을 나누는 이유, 서식 도구와 검사 도구까지 다뤄요.

중급강의 5 / 6약 10분

코드를 한 번 쓰는 동안, 그 코드는 수십 번 읽혀요. 버그를 찾을 때, 기능을 더할 때, 동료가 검토할 때, 그리고 석 달 뒤의 내가 "이게 뭐였지?" 할 때요. 그래서 좋은 코드의 첫째 조건은 컴퓨터가 아니라 사람이 읽기 쉬운 것이에요. 컴퓨터는 지저분한 코드도 잘 돌려요. 힘든 건 사람이에요.

읽기 쉬운 코드는 버그가 숨을 곳이 적고, 고치기 쉽고, 남에게 넘기기 쉬워요. 이번 강의에서는 그 조건들을 하나씩 보고, 실제로 지저분한 코드를 고쳐 봐요.

고쳐 볼 코드

장바구니의 결제 금액을 계산하는 함수예요. 동작은 해요. 그런데 읽어 보세요.

def calc(d, t):
    r = 0
    for i in d:
        if i[2] == True:
            if i[1] > 0:
                r = r + i[0] * i[1]
    if t == 1:
        r = r * 0.9
    elif t == 2:
        r = r * 0.8
    if r > 50000:
        pass
    else:
        r = r + 3000
    return r

cart = [(12000, 3, True), (8900, 1, False), (4500, 2, True)]
print(calc(cart, 0), calc(cart, 1), calc(cart, 2))
48000 43500.0 39000.0

d는 무엇이고 t는 무엇일까요? i[2]는? t == 1은 무슨 뜻이고, 50000과 3000은 어디서 온 숫자일까요? 코드를 쓴 사람의 머릿속에만 답이 있어요. 하나씩 고쳐 볼게요. 고치기 전에 지금의 결과를 시험으로 고정해 둬요. 정리하다가 동작이 바뀌면 바로 알 수 있게요.

cases = [
    ([(12000, 3, True), (8900, 1, False), (4500, 2, True)], 0),
    ([(12000, 3, True), (8900, 1, False), (4500, 2, True)], 1),
    ([(30000, 2, True)], 2),
    ([(5000, 0, True), (2000, 1, True)], 0),
    ([], 1),
]
expected = [calc(items, level) for items, level in cases]
print(expected)
[48000, 43500.0, 51000.0, 5000, 3000.0]

1. 이름이 뜻을 말하게

이름은 가장 싸고 강력한 설명이에요. 좋은 이름은 무엇을 담는지, 왜 있는지를 알려 줘요.

나쁜 이름좋은 이름이유
d, i, ritems, item, total무엇을 담는지 보여요
calcorder_total무엇을 계산하는지 보여요
tmember_level숫자 1, 2가 아니라 등급이라는 걸 알려요
flag, checkis_selected, has_coupon참과 거짓을 담는다는 게 보여요
data2, tempdiscounted_total둘째, 임시라는 말은 아무것도 알려 주지 않아요

몇 가지 요령이 있어요.

  • 줄임말을 피해요: cnt, usr_nm보다 count, user_name이 읽기 쉬워요. 타자 몇 번 아끼려다 읽는 사람이 해독해야 해요.
  • 같은 개념에는 같은 낱말을: 한 곳에서는 user, 다른 곳에서는 member, 또 다른 곳에서는 customer라고 부르면 서로 다른 것인지 헷갈려요.
  • 범위가 넓을수록 자세하게: 세 줄짜리 반복문의 i는 괜찮지만, 여러 함수에서 쓰는 값은 이름이 분명해야 해요.

2. 마법의 숫자에 이름 붙이기

코드 속의 50000, 3000, 0.9 같은 숫자를 마법의 숫자라고 불러요. 왜 그 값인지 알 수 없고, 바꿀 때 여기저기 흩어진 같은 숫자를 다 찾아야 해요. 이름을 붙인 상수로 바꿔요.

3. 숫자 대신 뜻 있는 구조

i[0], i[1], i[2]는 "가격, 수량, 선택 여부"라는 걸 외워야 읽을 수 있어요. 이름이 있는 구조를 써요. 파이썬의 dataclass가 편해요. 회원 등급도 숫자 1, 2 대신 이름으로 써요.

4. 한 가지 일만 하는 작은 함수

calc는 세 가지 일을 한꺼번에 해요. 상품 금액 합계, 회원 할인, 배송비. 각각을 이름 있는 함수로 나누면, 함수 이름만 읽어도 전체 흐름이 보이고, 하나씩 따로 시험할 수 있어요.

네 가지를 모두 적용하면 이렇게 돼요.

from dataclasses import dataclass

MEMBER_DISCOUNT = {"basic": 0.0, "silver": 0.10, "gold": 0.20}   # 회원 등급별 할인율
FREE_SHIPPING_OVER = 50_000                          # 이 금액을 넘으면 배송비 무료
SHIPPING_FEE = 3_000

@dataclass
class CartItem:
    price: int
    quantity: int
    is_selected: bool = True

def items_subtotal(items):
    return sum(item.price * item.quantity
               for item in items if item.is_selected and item.quantity > 0)

def apply_member_discount(amount, member_level):
    return amount * (1 - MEMBER_DISCOUNT[member_level])

def shipping_fee(amount):
    return 0 if amount > FREE_SHIPPING_OVER else SHIPPING_FEE

def order_total(items, member_level="basic"):
    discounted = apply_member_discount(items_subtotal(items), member_level)
    return discounted + shipping_fee(discounted)    # 배송비는 할인한 금액 기준이에요

LEVELS = {0: "basic", 1: "silver", 2: "gold"}
for (old_items, level), want in zip(cases, expected):
    items = [CartItem(price, quantity, selected) for price, quantity, selected in old_items]
    assert order_total(items, LEVELS[level]) == want
print("고친 코드도 결과가 모두 같아요")
고친 코드도 결과가 모두 같아요

코드가 길어졌지만 읽는 시간은 줄었어요. order_total의 두 줄만 읽어도 "상품 합계에 회원 할인을 하고, 할인한 금액에 배송비를 더한다"는 게 보여요. 배송비 정책이 바뀌면 shipping_fee만 보면 되고, 등급이 늘면 표에 한 줄만 더하면 돼요. 그리고 처음에 고정한 시험 덕분에 동작이 하나도 바뀌지 않았다는 확신을 갖고 고쳤어요.

이렇게 동작은 그대로 두고 구조만 다듬는 일을 리팩터링이라고 해요.

동작을 바꾸는 수정은 따로

고치다 보니 문제가 하나 보여요. 돈을 실수(float)로 계산하고 있어서 43500.0처럼 소수점이 붙고, 디버깅 강의에서 본 부동소수점 오차가 생길 수 있어요. 원 단위 정수로 계산하는 게 맞아요. 그런데 이건 동작을 바꾸는 수정이에요(소수점 아래를 어떻게 처리할지 정해야 하니까요). 리팩터링과 섞지 말고, 시험을 새로 정한 뒤 따로 고치고 따로 커밋해요. 섞으면 문제가 생겼을 때 정리 때문인지 수정 때문인지 알 수 없어요.

5. 중첩을 줄이는 이른 반환

조건이 겹겹이 쌓이면 읽는 사람이 머릿속에 조건을 계속 들고 있어야 해요.

def can_checkout_nested(user, cart):
    if user is not None:
        if not user.get("banned"):
            if cart:
                return True, ""
            else:
                return False, "장바구니가 비었어요"
        else:
            return False, "이용이 제한된 계정이에요"
    else:
        return False, "로그인이 필요해요"

안 되는 경우를 먼저 걸러 내고 바로 돌려주면(이른 반환) 평평해져요. 남은 코드는 "모든 조건을 통과한 경우"만 다루면 돼요.

def can_checkout(user, cart):
    if user is None:
        return False, "로그인이 필요해요"
    if user.get("banned"):
        return False, "이용이 제한된 계정이에요"
    if not cart:
        return False, "장바구니가 비었어요"
    return True, ""

for user, cart in [(None, [1]), ({"banned": True}, [1]), ({}, []), ({}, [1])]:
    assert can_checkout(user, cart) == can_checkout_nested(user, cart)
    print(can_checkout(user, cart))
(False, '로그인이 필요해요')
(False, '이용이 제한된 계정이에요')
(False, '장바구니가 비었어요')
(True, '')

6. 주석은 "왜"를 적어요

좋은 이름과 작은 함수가 무엇을 하는지 말해 주니, 주석은 코드만으로는 알 수 없는 왜를 적어요.

# 나쁜 주석: 코드를 그대로 다시 읽어 줄 뿐이에요
count = 0  # count를 0으로 둔다

# 좋은 주석: 코드에 드러나지 않는 이유를 알려 줘요
RETRY_LIMIT = 3  # 결제사 API가 가끔 일시 오류를 내서, 세 번까지는 다시 시도해요 (네 번째부터는 대부분 진짜 장애)
  • 주석으로 나쁜 이름을 덮지 않아요. d = [] # 주문 목록이라면 이름을 orders로 바꾸는 게 맞아요.
  • 지운 코드를 주석으로 남겨 두지 않아요. 옛 코드는 Git이 기억해요. 주석 처리된 코드는 "이거 다시 쓰는 건가?" 하는 혼란만 남겨요.
  • 주석도 코드와 함께 고쳐요. 틀린 주석은 주석이 없는 것보다 나빠요.
  • 함수가 무엇을 받고 무엇을 돌려주는지는 독스트링(함수 첫 줄의 설명 문자열)에 적어요. 문서 읽기 강의에서 본 help()와 편집기가 이걸 보여 줘요.

7. 서식은 도구에게 맡기기

들여쓰기, 띄어쓰기, 줄 길이 같은 서식은 사람마다 취향이 달라서, 팀에서 토론하기 시작하면 끝이 없어요. 그래서 자동 서식 도구에 맡겨요. 파이썬은 PEP 8이라는 공식 스타일 안내가 있고, ruff나 black 같은 도구가 저장할 때마다 코드를 그 모양으로 맞춰 줘요. 검사 도구(린터)는 쓰지 않는 변수, 정의하지 않은 이름, 위험한 습관을 찾아 줘요. 편집기에 연결해 두면 쓰는 동안 바로 알려 줘요.

pip install ruff
ruff check .          # 문제를 찾아요
ruff format .         # 서식을 맞춰요

타입 힌트도 읽기를 돕는 도구예요. def shipping_fee(amount: int) -> int:처럼 적으면 무엇을 받고 돌려주는지 바로 보이고, 검사 도구가 잘못 쓴 곳을 찾아 줘요.

과하지 않게

읽기 쉬운 코드를 만들다 보면 반대로 너무 멀리 가기도 해요.

  • 너무 이른 추상화: 비슷한 코드가 두 번 나왔다고 바로 공통 함수로 묶으면, 나중에 둘이 조금씩 달라질 때 함수가 조건문 덩어리가 돼요. 흔히 세 번째로 반복될 때 묶으라고 해요.
  • 너무 잘게 쪼개기: 한 줄짜리 함수를 수십 개 만들면 흐름을 따라가려고 여기저기 뛰어다녀야 해요.
  • 영리한 한 줄: 한 줄에 모든 걸 넣은 코드는 쓰는 사람은 뿌듯하지만 읽는 사람은 괴로워요. 두세 줄로 풀어 쓰는 게 나을 때가 많아요.

기준은 늘 같아요. 처음 보는 동료가 빨리 이해할 수 있는가.

습관으로 만들기

  • 보이스카우트 규칙: "캠핑장을 처음보다 깨끗하게 하고 떠나라." 코드를 고치러 들어갔다면 근처의 나쁜 이름 하나, 마법의 숫자 하나라도 정리하고 나와요. 다만 동작을 바꾸는 수정과는 커밋을 나눠요.
  • 시험이 안전망: 시험이 없는 코드는 고치기 무서워요. 리팩터링 전에 지금 동작을 시험으로 고정해요. 위에서 expected를 먼저 만든 것처럼요.
  • 코드 검토에서 배우기: 동료의 검토 의견은 읽기 쉬움에 대한 가장 좋은 측정이에요. "이 부분이 이해가 안 돼요"라는 말은 코드를 고치라는 신호예요.

실습

  1. order_total에 "쿠폰 금액을 빼는" 기능을 더해 보세요. 어느 함수를 고치고, 어떤 시험을 더해야 할까요?
  2. 돈을 원 단위 정수로 계산하도록 바꿔 보세요. 할인 뒤 소수점 아래는 버리기로 하고, 시험의 기대값을 새로 정하세요.
  3. 예전에 쓴 코드 하나를 열어, 이름 세 개를 더 좋은 이름으로 바꿔 보세요.
  4. ruff check를 내 프로젝트에 돌려 보고, 나온 경고 하나의 뜻을 문서에서 찾아보세요.
  5. 다섯 단계 이상 중첩된 조건문을 찾아 이른 반환으로 평평하게 만들어 보세요. 고치기 전과 후의 결과가 같은지 시험으로 확인하세요.

자주 하는 실수

  • 시험 없이 리팩터링하기. 동작이 바뀌어도 알아채지 못해요.
  • 리팩터링과 기능 수정을 한 커밋에 섞기. 문제가 생기면 원인을 가를 수 없어요.
  • 주석으로 나쁜 이름 덮기. 이름을 고쳐요.
  • 줄임말과 한 글자 이름 남발하기. 읽는 사람이 해독해야 해요.
  • 서식 논쟁하기. 도구에 맡기고 내용에 집중해요.
  • 두 번 나왔다고 바로 묶기. 세 번째에 묶어도 늦지 않아요.

점검 문제

  1. 코드를 읽기 쉽게 써야 하는 가장 큰 이유는?
  2. 마법의 숫자란 무엇이고, 어떻게 고치나요?
  3. calc를 고칠 때 가장 먼저 한 일은 무엇이고, 왜 그렇게 했나요?
  4. 리팩터링이란? 돈 계산을 정수로 바꾸는 것은 리팩터링인가요?
  5. 이른 반환이 읽기를 돕는 이유는?
  6. 좋은 주석은 무엇을 적나요? 나쁜 주석의 예는?
  7. 공통 함수로 묶는 시점에 대한 흔한 기준은?

정답

  1. 코드는 쓰는 것보다 훨씬 많이 읽히기 때문이에요. 읽기 쉬우면 버그를 찾고 고치고 넘기기 쉬워요.
  2. 의미를 알 수 없는 숫자가 코드에 그대로 박혀 있는 거예요. SHIPPING_FEE = 3_000처럼 이름 붙인 상수로 바꿔요.
  3. 여러 경우의 현재 결과를 시험으로 고정했어요. 고치는 동안 동작이 바뀌지 않았는지 확인하기 위해서예요.
  4. 동작은 그대로 두고 구조만 다듬는 일이에요. 돈을 정수로 바꾸면 결과(소수점 처리)가 바뀌니 리팩터링이 아니라 동작 변경이고, 따로 해야 해요.
  5. 안 되는 경우를 먼저 걸러 내서 중첩이 사라지고, 남은 코드는 조건을 모두 통과한 경우만 다루면 되기 때문이에요.
  6. 코드만으로는 알 수 없는 이유(왜)를 적어요. 코드를 그대로 다시 읽어 주는 주석(count = 0 # count를 0으로 둔다)이 나쁜 예예요.
  7. 같은 코드가 세 번째로 반복될 때 묶으라는 기준이 흔해요.

다음 강의

성장 트랙의 마지막 강의에서는 이 모든 것을 한데 모으는 방법, 프로젝트로 배우기를 다뤄요. 무엇을 만들지 고르는 법, 작게 시작해 끝까지 완성하는 법, 그리고 막혔을 때 앞의 강의들을 어떻게 꺼내 쓰는지 정리해요.