파이썬 주석 & 타입 힌트 완벽 가이드 | PEP 8, Docstring까지 한 번에 정리

1 주석 (Comment)

1) 기본

→ 코드에 대한 설명이며, 실행 시 무시가 됨

→ 내가 나중에 다시 봐도 이해하기 쉬움

→ 다른 사람과 협업할 때도 코드 읽기가 편해짐

---

2) 작성법

→ 한 줄 주석은 #을 먼저 쓰고 한 칸 공백을 띄운 후 작성함

→ 여러 줄 주석은 줄마다 #을 먼저 쓰고 한 칸 공백을 띄운 후 작성함

※ 들여쓰기에 맞춰 주석도 정렬을 하면 가독성이 좋아짐

---

3) 활용 예시

1-1 코드 : 코드 설명

# 사용자로부터 나이를 입력받아 정수로 변환
age = int(input("나이를 입력하세요: "))

1-2 코드 : 디버깅 혹은 임시 비활성화

# print("이 줄은 디버깅 때문에 꺼둠")

1-3 코드 : 색션 구분

# --- 입력 ---
# --- 처리 ---
# --- 출력 ---

1-4 코드 : TODO와 변경 기록

# TODO: 나이 입력 기능 추가
# 2025-09-10: 출력 메시지 수정

1-5 코드 : 출력 확인용

result = 3 + 5
# print("디버깅용:", result)  # 확인 끝나면 주석 처리

---

4) 좋은 주석 습관 (PEP 8)

→ 무엇(What) 보다는 왜(Why)를 설명하기

→ 코드를 수정할 시 주석도 함께 수정하기

→ 불필요한 주석은 코드를 방해하지 않도록 삭제하기

→ 한 줄은 72자 이하를 권장함

---

2 Docstring (PEP 257)

→ 함수 또는 클래스 또는 모듈을 설명하기 위한 삼중 따옴표 문법

→ 첫 줄은 한 줄을 요약함

→ 그 다음 줄부터 필요하면 빈 줄을 추가 후 설명함

→ IDE 혹은 자동 문서화 도구에서 바로 확인이 가능함

2-1 코드

def add(a, b):
    """두 수를 더해 결과를 반환"""
    return a + b

---

3 자동 문서화 활용

→ 주석과 Docstring은 문서화 도구로 변환할 수 있음

도구	특징	추천
pdoc	빠르고 심플함	개인 프로젝트
Sphinx	강력하며, 확장이 가능함	대규모 프로젝트
mkdocstrings	Markdown 기반	블로그 스타일 문서

※ GitHub Pages, Read the Docs에 배포하면 무료로 웹 문서화가 가능함

---

728x90

4 타입 힌트 (Type Hint)

→ 변수와 함수의 자료형을 코드에 직접 명시하는 기능

3-1 코드 : 기본 문법

def add(a: int, b: int) -> int:
    return a + b

3-2 코드 : 컬렉션 타입

numbers: list[int] = []
scores: dict[str, int] = {"math": 90}

3-3 코드 : 추가 문법

from typing import Optional, Any, Literal

name: Optional[str] = None      # None 허용
value: Any = 10                 # 어떤 타입이든 허용
status: Literal["open", "closed"] = "open"  # 특정 값만 허용

※ 타입 힌트는 런타임 강제가 아니므로, mypy, pyright 같은 정적 타입 검사기로 점검을 추천함

---

5 주석과 타입 힌트를 같이 쓰기

→ 주석은 의도(Why)를, 타입 힌트는 자료형을 설명하여 둘을 같이 쓰면 최강 조합이 됨

4-1 코드

def greet(name: str) -> str:
    """사용자 이름을 받아 인사말 반환"""
    # name: 사용자 이름 (예: 'Alice')
    return f"Hello, {name}!"

---

6 BEST PRACTICE

→ 타입은 타입 힌트로, 설명은 Docstring과 주석으로 하기

→ 주석은 짧고 명확하게 하고, 코드와 함께 수정하기

→ mypy, pyright 같은 정적 타입 검사기로 정적 타입을 검사하여 버그를 사전에 차단하기

→ 팀 프로젝트에서는 Optional, Union, Any를 최소화하고, 타입 표기 방식을 통일하기

---

Python 주석에 대해 더 상세한 설명을 원하는 분들은 아래 사이트에 접속하기

☞ Python 주석

---

Python 주석 뿐만 아니라 다른 프로그래밍 언어에 대해 알고 싶은 분들은 아래 사이트에 접속하여 원하는 링크에 접속하기

☞ 프로그래밍 언어 링크 모음