파이썬(Python) 주석 처리 방법, 한 줄·여러 줄·독스트링 직접 해 보니

맥 한 대에서 파이썬 3.15.0으로 주석 예제를 한 번씩 실행해 봤습니다. #로 시작한 줄은 출력에 아무것도 남기지 않았고, 삼중따옴표로 감싼 글은 str 값으로 그대로 남았습니다. 함수 첫 줄에 둔 문자열은 __doc__과 help()로 다시 읽을 수 있었죠. 파이썬 주석을 #으로 쓸지 삼중따옴표로 쓸지 헷갈렸다면 아래 코드와 출력을 그대로 따라 해 보세요. Claude Code에게 docstring을 달게 한 마지막 단계도 7.0초 만에 종료 코드 0으로 끝났습니다.

따라 할 순서 한눈에 보기

1. python3 --version으로 쓰는 파이썬 버전을 확인합니다.
2. 줄 맨 앞과 줄 끝에 #을 붙여 한 줄 주석을 달고, 코드 앞에 #을 붙여 그 줄을 끕니다.
3. 여러 줄을 설명할 때는 줄마다 #을 붙입니다.
4. 삼중따옴표(""")로 감싼 글이 주석이 아니라 문자열이라는 점을 확인합니다.
5. 함수 첫 줄에 docstring을 쓰고 __doc__과 help()로 읽어 봅니다.
6. 문자열 안의 #은 주석이 아니라는 점을 확인합니다.
7. Claude Code에게 docstring을 달게 한 뒤 실행해서 읽어 봅니다.

이 실행에서 일곱 단계 모두 종료 코드 0으로 끝났고, 오류가 난 단계는 없었습니다. 그럼 단계마다 실제 코드와 출력을 보겠습니다.

함께 읽을 글

• 파이썬(Python) 딕셔너리 사용법, 자주 쓰는 동작을 직접 실행해 보니
• 파이썬(Python) 컴파일, pyc 파일이 생기는 과정 직접 해 보니
• 파이썬(Python) 리스트 사용법, 자주 쓰는 동작을 직접 해 보니

먼저 파이썬 버전 확인하기

예제는 이 컴퓨터에 Homebrew로 설치돼 있던 python3로 돌렸습니다. 코드는 단계마다 python3 - <<'PY' ... PY 형태로 표준 입력에 넣어 바로 실행했어요.

$ python3 --version
Python 3.15.0

한 줄 주석과 코드 끄기

가장 기본은 #입니다. 줄 맨 앞에 쓰면 그 줄 전체가, 코드 뒤에 쓰면 그 자리부터 줄 끝까지가 주석이 됩니다. 실행 중인 코드를 잠깐 끄고 싶을 때도 맨 앞에 #만 붙이면 되죠.

$ python3 - <<'PY'
# 이 줄은 실행되지 않는다
print("첫 줄")  # 줄 끝 주석
# print("주석 처리한 코드")
print("셋째 줄")
PY
첫 줄
셋째 줄

출력에는 "첫 줄"과 "셋째 줄"만 남았습니다. Python 공식 문서의 어휘 분석에 따르면 주석은 문자열 리터럴에 들어 있지 않은 #로 시작해 물리적인 줄 끝에서 끝나고, 문법은 주석을 무시합니다. 그래서 #이 붙은 print는 아예 실행되지 않았어요.

파이썬 여러줄 주석은 어떻게 쓰나요?

파이썬에는 여러 줄을 한 번에 감싸는 주석 기호가 따로 없습니다. 그래서 줄마다 #을 붙이는 방식을 씁니다.

$ python3 - <<'PY'
# 여러 줄을 설명할 때는
# 줄마다 #을 붙인다
total = 1 + 2
print(total)
PY
3

그런데 삼중따옴표로 여러 줄을 감싸도 실행은 되잖아요? 겉보기엔 주석 같지만, 실제로 파이썬이 어떻게 받아들이는지 확인해 보면 이렇습니다.

$ python3 - <<'PY'
"""
이 부분은 주석처럼 보이지만 문자열이다
"""
note = """여러 줄
문자열"""
print(type(note).__name__, repr(note))
PY
str '여러 줄\n문자열'

note의 타입은 str이었고, 줄바꿈도 \n으로 그대로 남았습니다. 공식 문서도 삼중따옴표 문자열은 줄바꿈을 허용하고 그대로 보존한다고 설명해요. 이 실행에서 직접 확인한 건 변수에 담은 쪽이지만, 맨 위에 떠 있는 삼중따옴표 덩어리도 문법상 문자열 리터럴입니다. 게다가 PEP 257에 따르면 모듈의 첫 문장으로 나온 문자열은 그 모듈의 docstring이 됩니다. 순수하게 설명만 남기려면 #을 쓰는 쪽이 의도에 맞습니다.

함수 첫 줄 설명은 어떻게 읽나요?

삼중따옴표가 제 역할을 하는 자리는 함수·클래스·모듈의 첫 문장입니다. PEP 257은 이 자리의 문자열을 docstring이라 부르고, 그 객체의 __doc__ 속성이 된다고 정의합니다.

$ python3 - <<'PY'
def add(a, b):
    """두 수를 더해 돌려준다."""
    return a + b
print(add.__doc__)
help(add)
PY
두 수를 더해 돌려준다.
Help on function add in module __main__:

add(a, b)
    두 수를 더해 돌려준다.

__doc__은 문자열을 그대로 돌려줬고, help()는 함수 이름·인자와 함께 같은 설명을 보여 줬습니다. PEP 257은 한 줄 docstring도 나중에 늘리기 쉽도록 삼중 큰따옴표를 쓰고, 닫는 따옴표를 같은 줄에 두며, 마침표로 끝나는 문장으로 쓰라고 권합니다. 반대로 다른 자리에 둔 문자열은 __doc__에 담기지 않는다고 하니, 위치가 핵심이에요.

도식출처: 직접 실행한 순서

문자열 안의 #은 왜 주석이 아닐까요?

URL이나 색상 코드처럼 #이 들어간 값을 다룰 때가 많죠. 이럴 때는 따옴표 안의 #이 주석으로 처리될지 걱정될 수 있습니다.

$ python3 - <<'PY'
url = "https://example.com/#section"
print(url)  # 문자열 안의 #은 주석이 아니다
PY
https://example.com/#section

URL은 #section까지 온전히 출력됐습니다. 앞에서 본 정의대로 주석은 문자열 리터럴에 들어 있지 않은 #부터 시작하기 때문입니다. 같은 줄 뒤쪽, 따옴표 밖에 있는 #만 주석이 됐어요.

도식출처: 근거를 바탕으로 코드가 그린 도식

AI에게 docstring을 맡기면 어떻게 나올까요?

Claude Code로 함수를 만들고 있다면 설명까지 맡기고 싶을 겁니다. 마지막 단계에서는 이미 로그인된 Claude Code에 --model opus로 요청하고, 결과를 파일로 저장해 바로 실행했습니다.

$ claude --model opus -p "파이썬 함수 def area(w, h): return w * h 에 한국어 docstring을 달고, 그 아래에 print(area.__doc__)를 넣은 코드만 출력해. 설명이나 코드 블록 표시는 붙이지 마." > area.py && cat area.py && python3 area.py
def area(w, h):
    """직사각형의 넓이를 계산하여 반환한다.

    Args:
        w: 가로 길이
        h: 세로 길이

    Returns:
        가로와 세로를 곱한 넓이
    """
    return w * h


print(area.__doc__)
직사각형의 넓이를 계산하여 반환한다.

Args:
    w: 가로 길이
    h: 세로 길이

Returns:
    가로와 세로를 곱한 넓이

위 코드는 이번 한 번의 실행에서 나온 결과이고, 같은 요청이라도 실행할 때마다 내용과 형식이 달라질 수 있습니다. 이번 결과는 PEP 257이 말하는 여러 줄 docstring 짜임(요약 한 줄, 빈 줄, 자세한 설명)을 따랐고, 닫는 따옴표도 따로 한 줄에 뒀습니다. 그래서 요청에 print(area.__doc__)까지 넣어 두면, AI가 쓴 설명이 정말 docstring 자리에 들어갔는지 실행 한 번으로 확인할 수 있어요.

자주 하는 실수와 점검 목록

여기까지의 실행과 공식 문서를 바탕으로, 혼자 코드를 쌓아 갈 때 걸리기 쉬운 지점을 모았습니다.

• 삼중따옴표를 주석으로 믿기: 문자열입니다. 함수나 모듈의 첫 문장 자리에 오면 docstring이 됩니다.
• docstring을 함수 중간에 두기: PEP 257에 따르면 첫 문장이 아닌 문자열은 __doc__에 담기지 않습니다.
• 역슬래시 줄에 주석 달기: 공식 문서는 역슬래시로 끝나는 줄에는 주석을 넣을 수 없다고 합니다. 괄호로 묶어 이어지는 줄에는 주석을 달 수 있습니다.
• 문자열 속 #을 지우기: 따옴표 안의 #은 값의 일부라서 지우면 값이 바뀝니다.

AI가 고친 코드를 받았다면 아래 항목을 점검해 보세요.

• 꺼 둔 코드 앞에 #이 제대로 붙어 있는지
• 설명용 여러 줄이 #으로 되어 있는지
• 함수 설명이 함수 첫 줄에 삼중 큰따옴표로 들어갔는지
• help(함수이름)으로 설명이 읽히는지

측정 조건과 한계

모든 단계는 2026-10-27 15:28 KST에 새 임시 폴더 하나에서 적힌 차례대로 한 번씩만 실행했습니다. 환경은 맥(darwin arm64), Node.js v22.23.1, Claude Code 2.1.309, Homebrew로 설치된 Python 3.15.0입니다.

한 번만 잰 값이라 Claude Code 단계의 7.0초는 네트워크나 모델 응답에 따라 달라질 수 있습니다. 이 측정만으로는 시간이 어디서 쓰였는지 가를 수 없으니, 직접 확인하려면 같은 명령을 여러 번 돌려 비교해 보세요. 주석과 docstring의 동작 자체는 위 출력과 공식 문서가 말하는 범위에서만 확인했습니다.