Python / 문법 / 주석

Python

Python의 주석은 문자열 바깥의 #에서 시작해 그 줄의 끝까지 이어집니다. 여러 줄을 주석으로 쓰려면 각 줄에 #를 붙이며, 따옴표 세 개로 만든 문장은 주석 문법이 아니라 문자열 리터럴입니다. 함수 등의 첫 문장에 놓인 문서 문자열인 docstring도 일반 주석과 구분해야 합니다.

한 줄 주석과 문자열 안의 #

주석은 코드의 의도와 조건을 설명하는 글이며, 일반적인 주석 내용은 Python 문법 분석에서 무시됩니다. 한 줄 전체를 설명으로 쓰거나 코드 뒤에 짧게 덧붙일 수 있습니다. 정확한 범위는 Python의 주석 규칙을 참고합니다.

다음 예제는 Python 3만 필요합니다. 전체를 UTF-8의 comments_example.py로 저장한 뒤 python comments_example.py로 실행합니다. 환경에 따라 python3을 사용하며, 뒤의 예제도 파일 내용을 교체해 독립적으로 실행할 수 있습니다.

# Calculate the total before discounts.
price = 100
quantity = 2  # Number of items
print(price * quantity)

예상 결과는 다음과 같습니다.

#가 따옴표 안에 있으면 문자열의 일부입니다. 따라서 해시가 포함된 문구나 URL 조각은 주석으로 잘리지 않습니다.

print("# This is part of a string")
print("https://example.com/page#section")

# This is part of a string
https://example.com/page#section

여러 줄 설명은 각 줄에 #을 붙입니다

Python에는 C 언어의 /* ... */ 같은 별도의 블록 주석 문법이 없습니다. 여러 줄 설명은 아래처럼 각 줄을 주석으로 작성합니다. 설명할 코드와 들여쓰기를 맞추면 어느 블록에 관한 설명인지 파악하기 쉽습니다.

# The sample uses a fixed discount rate.
# Production rules may depend on the customer.
base_price = 100
discount_rate = 0.1
print(base_price * (1 - discount_rate))

90.0

코드를 잠시 실행하지 않게 하려면 해당 코드의 각 줄을 주석 처리하고, 다시 실행하려면 그 줄의 주석 표시를 해제합니다. 편집기의 여러 줄 주석 기능도 보통 이 방식으로 동작합니다. 오래 보관할 이전 구현은 주석으로 계속 쌓기보다 버전 관리 이력으로 남기는 편이 현재 코드를 읽기 쉽습니다.

따옴표 세 개와 docstring은 문자열입니다

''' 또는 """로 둘러싼 내용은 여러 줄을 담을 수 있는 문자열 리터럴입니다. 모듈·클래스·함수의 첫 문장에 놓은 문자열은 docstring으로 인식되어 __doc__이나 도움말에서 사용됩니다. 문서 문자열 공식 설명에서 위치와 용도를 확인할 수 있습니다.

def greet(name):
    """Return a greeting for name."""
    return f"Hello, {name}"

print(greet("Ada"))
print(greet.__doc__)

Hello, Ada
Return a greeting for name.

이 문자열은 함수를 문서화하는 값으로 접근할 수 있으므로 단순히 실행에서 제외한 설명과 다릅니다. 같은 따옴표 형식은 다음처럼 실제 데이터를 담는 데도 사용합니다.

notes = """first line
second line"""
print(notes.splitlines())

['first line', 'second line']

임의의 코드를 따옴표 세 개로 감싸면 진짜 주석이 되는 것은 아닙니다. 감싼 코드에 같은 따옴표가 있으면 구문이 깨질 수 있고, 문자열의 위치에 따라 문서 문자열로 해석될 수도 있습니다. 코드를 비활성화하려면 #를 사용합니다.

주석만 있는 코드 블록에는 pass가 필요합니다

def·if 등으로 만든 블록에는 실제 문장이 필요합니다. 주석은 문장으로 계산되지 않으므로 본문에 주석만 남기면 IndentationError가 발생할 수 있습니다. 아무 동작도 하지 않는 자리표시자로 pass 문을 사용합니다.

source = "def todo():\n    # Implement later\n"
try:
    compile(source, "example", "exec")
except IndentationError:
    print("IndentationError")

def todo():
    # Implement later
    pass

print(todo())

IndentationError
None

첫 부분은 잘못된 코드를 문자열로 만들어 컴파일 오류를 확인한 것입니다. 직접 파일 전체가 멈추지 않도록 예외를 잡았습니다. 아래 함수는 pass 덕분에 정상 정의되며, 명시적 반환문이 없어 호출 결과는 None입니다.

읽기 좋은 주석과 특별한 지시문

파이썬 개선 제안서인 PEP(Python Enhancement Proposal) 중 PEP 8의 주석 지침은 코드와 맞지 않는 주석을 경계합니다. 코드가 무엇을 하는지 그대로 반복하기보다 선택한 이유, 외부 제약과 주의할 조건을 설명하고 코드 변경 시 함께 갱신합니다. 일반적인 인라인 주석은 코드와 두 칸 이상 띄우고 # 뒤에 한 칸을 두는 형식을 권장합니다.

일부 주석은 별도 도구나 파일 처리 규칙에서 특별한 의미를 가집니다. 예를 들어 소스 파일의 첫째 또는 둘째 줄에 놓인 올바른 인코딩 선언은 파일 해석에 영향을 줄 수 있습니다. Python 3의 기본 소스 인코딩은 UTF-8입니다. 린터·타입 검사기의 전용 지시문도 일반 설명과 구분하고, 원인을 확인하지 않은 채 경고를 일괄 숨기지 않습니다.

Python