6개월 전에 내가 짠 코드를 다시 열어 본 적 있나. 분명 내 손으로 쓴 건데 “이걸 대체 왜 이렇게 짰지?” 싶어 한참을 멍하니 들여다본다. 남이 쓴 코드도 아니고 과거의 나조차 못 알아보는 그 순간, 파이썬 주석의 가치를 뼈저리게 깨닫게 된다. 주석은 코드를 꾸미는 장식이 아니다. 미래의 나와 동료를 구하는 가장 값싼 보험이다.
주석은 왜 중요한가
코드는 컴퓨터에게 일을 시키는 명령어다. 그런데 그 명령어를 읽는 건 컴퓨터만이 아니다. 같이 일하는 동료가 읽고, 몇 달 뒤의 내가 읽고, 운이 나쁘면 내가 퇴사한 뒤 누군가가 새벽에 장애를 잡으며 읽는다. 아무리 뛰어난 개발자라도 낯선 코드만 보고 그 의도와 흐름을 단번에 파악하긴 어렵다.
그래서 좋은 프로그래머들은 자기 코드 옆에 짧은 설명을 남기기 시작했다. 이게 바로 주석이다. 코드가 “무엇을 하는가”는 코드 자체가 말해 주지만, “왜 이렇게 했는가”는 작성자만 안다. 그 이유를 붙잡아 두는 장치가 주석이다. 협업할 때 주석 하나가 서로의 시간을 몇 시간씩 아껴 주는 이유가 여기 있다.
파이썬 주석 기본 문법
모든 프로그래밍 언어에는 주석을 위한 문법이 있다. 다만 그 모양은 언어마다 조금씩 다르다. 파이썬은 # 기호를 쓴다. 한 줄에서 #을 만나면 그 뒤부터 줄 끝까지는 전부 주석으로 처리하고, 파이썬은 그 부분을 실행하지 않고 건너뛴다.
# Hello World를 출력하는 예제다.
print("Hello, World")위 코드를 실행하면 결과는 이렇게 나온다.
Hello, World첫 줄은 #으로 시작했으니 파이썬이 그냥 무시한다. 만약 # 없이 한글 설명을 그대로 적었다면 파이썬은 그 문장을 명령어로 해석하려다 에러를 뱉었을 것이다. # 하나가 “이 줄은 사람을 위한 메모니까 신경 쓰지 마”라고 알려 주는 신호인 셈이다.
주석은 두 가지 방식으로 쓴다. 코드 한 줄 옆에 붙이는 인라인 주석과, 코드 위에 따로 한 줄을 차지하는 블록 주석이다.
total = price * 1.1 # 부가세 10%를 포함한 최종 금액
# 재고가 0 이하면 품절 처리한다
if stock <= 0:
status = "sold_out"인라인 주석을 쓸 때는 코드와 # 사이를 최소 두 칸 띄우는 게 보기 좋다. 사소해 보여도 파이썬 공식 스타일 가이드인 PEP 8이 권하는 규칙이다.
파이썬에 여러 줄 주석이 있을까
다른 언어를 먼저 배운 사람은 슬래시와 별표로 여러 줄을 감싸는 블록 주석 문법을 찾는다. 그런데 파이썬에는 그런 전용 멀티라인 주석 문법이 없다. 여러 줄을 주석 처리하려면 각 줄 앞에 #을 붙이는 게 정석이다.
# 이 함수는 사용자 입력을 검증한다.
# 빈 값이나 공백만 있는 경우를 걸러내고,
# 통과한 값만 다음 단계로 넘긴다.
def validate(text):
return bool(text.strip())"""...""" 삼중 따옴표로 여러 줄을 묶어 비슷한 효과를 내기도 한다. 하지만 엄밀히 말하면 그건 주석이 아니라 문자열이다. 함수나 클래스 바로 아래에 쓰면 docstring이라는 특별한 역할을 하니까, 단순 주석 대용으로 남발하는 건 피하는 게 좋다. docstring은 잠시 뒤에 따로 다룬다.
좋은 주석과 나쁜 주석의 차이
여기서부터가 입문과 실력의 갈림길이다. 주석은 많이 단다고 좋은 게 아니다. 오히려 잘못 단 주석은 없느니만 못하다.
가장 흔한 실수는 코드를 그대로 우리말로 옮겨 적는 주석이다.
i = i + 1 # i에 1을 더한다이런 주석은 아무 정보도 주지 않는다. 코드만 봐도 다 아는 내용을 반복할 뿐이다. PEP 8도 “뻔한 내용을 말하는 인라인 주석은 산만하기만 하다”고 분명히 적어 뒀다. 좋은 주석은 코드가 “어떻게”가 아니라 “왜”를 설명한다.
# 외부 API가 가끔 0을 음수로 반환해서 방어 코드를 둔다
if value < 0:
value = 0이 주석은 코드만 봐선 절대 알 수 없는 맥락을 담고 있다. 나중에 누군가 “이 조건문 왜 있지?” 하고 지우려다, 주석 덕분에 손을 멈춘다. 이게 주석이 밥값을 하는 순간이다.
한 가지 더. 주석은 코드와 함께 늙는다. 코드를 고치고 주석을 안 고치면, 거짓말하는 주석이 된다. 틀린 주석은 없는 주석보다 훨씬 위험하다. 읽는 사람을 엉뚱한 방향으로 끌고 가니까. 코드를 손볼 때 주석도 같이 손보는 습관을 들이자.
주석을 넘어, docstring
함수나 클래스가 “무엇을 위한 것인지” 설명할 때는 일반 주석 대신 docstring을 쓴다. 함수 정의 바로 아래에 삼중 따옴표로 적는 문서 문자열이다.
def calculate_tax(price, rate=0.1):
"""상품 가격에 세율을 적용해 세금을 계산한다.
Args:
price: 세전 가격
rate: 적용 세율 (기본값 0.1)
Returns:
계산된 세금 금액
"""
return price * ratedocstring의 장점은 단순한 메모를 넘어선다. 파이썬 내장 함수 help()로 바로 꺼내 볼 수 있고, 코드 에디터가 자동완성 설명으로 띄워 주기도 한다. 작성 규칙은 파이썬 docstring 표준인 PEP 257에 정리돼 있다. 기억하기 쉬운 기준 하나. 주석(#)은 “코드가 어떻게 돌아가는지”를, docstring은 “이 코드가 무엇을 위한 것인지”를 설명한다.
AI 코딩 시대에도 주석이 필요할까
요즘은 깃허브 코파일럿이나 커서 같은 AI 도구가 코드를 척척 짜 준다. 그럼 주석은 이제 필요 없을까. 오히려 반대다.
AI는 잘 쓰인 주석과 docstring을 읽고 맥락을 파악한다. 주석이 명확할수록 AI가 내 의도에 맞는 코드를 제안한다. 사람이 읽기 좋은 코드가 결국 AI도 읽기 좋은 코드인 셈이다. 게다가 AI가 만들어 준 코드를 그대로 믿고 넘기면 위험하다. “이 부분은 왜 이렇게 됐지?”를 내가 주석으로 정리해 두면, 나중에 그 코드를 검토하고 디버깅하기가 훨씬 수월하다. 더 깊은 작성 습관은 파이썬 개발을 위한 현대적 모범 사례에서 이어 볼 수 있다. 코드 한 줄도 더 깔끔하게 다듬는 법은 Real Python의 PEP 8 가이드가 친절하게 풀어 준다.
오늘 바로 써먹는 주석 체크리스트
기초를 익혔으니 실전에서 바로 점검할 거리를 정리한다.
- 코드를 그대로 번역한 주석은 지운다. 코드만 봐도 아는 건 안 적는다
- “어떻게”가 아니라 “왜”를 적는다. 의도와 배경을 남긴다
- 코드를 고치면 주석도 같이 고친다. 거짓 주석을 만들지 않는다
- 함수와 클래스에는 docstring으로 용도를 한 줄이라도 남긴다
- 인라인 주석은 코드와 두 칸 이상 띄운다
주석을 잘 다는 습관은 결국 코드를 읽는 사람을 배려하는 태도다. 그 배려가 협업의 질을 바꾸고, 6개월 뒤의 나를 구한다.
친절한 코드가 실력이다
처음 프로그래밍을 배울 때는 “돌아가기만 하면 된다”고 생각하기 쉽다. 하지만 진짜 실력은 남이 읽을 수 있는 코드, 미래의 내가 다시 이해할 수 있는 코드에서 드러난다. 파이썬 주석은 그 친절함을 코드에 새기는 가장 기본적인 도구다.
# 하나 붙이는 데 1초도 안 걸린다. 그 1초가 누군가의 한 시간을 아낀다. 다음 단계로 파이썬의 연산자를 익히거나, 코드를 더 단단하게 구조화하는 파이썬 객체 지향 프로그래밍으로 넘어가 보자. 그 전에, 오늘 짠 코드 한 줄 위에 “왜 이렇게 했는지” 한 줄만 남겨 보자. 친절한 프로그래머의 첫걸음은 거기서 시작된다.
참고 자료: Python Software Foundation, "PEP 8 – Style Guide for Python Code"