답변.

질문의 역사

파이썬은 초기 버전부터 코드를 docstring을 통해 문서화하는 것을 장려해왔습니다. Python 3.5(PEP 484)의 등장으로 가독성을 높이고 타입 분석기(예: mypy, pyright 등)의 지원을 개선하기 위해 타입 주석(type hints)이 추가되었습니다. 이렇게 함으로써 함수 및 클래스 정의에서 문서화와 타입화를 통합할 수 있습니다.

문제

타입 주석이 없으면 함수가 무엇을 처리하는지, 그에 대한 기대가 무엇인지 빠르게 이해하기 어렵습니다. 좋은 docstring의 부족은 인터페이스에 대한 오해와 사용 오류로 이어집니다. type hints 또는 docstrings를 잘못 사용하면 정적 분석을 방해하고 코드 지원을 악화시킬 수 있습니다.

해결책

함수의 목적, 매개변수 및 결과를 문서화하기 위해 여러 줄의 docstring을 사용하고, 인수 및 반환 값의 타입을 명시적으로 지정하기 위해 type hints를 사용하는 것이 좋습니다.

코드 예제:

def add_numbers(a: int, b: int) -> int:
    """
    두 정수를 더하고 결과를 반환합니다.

    :param a: 첫 번째 더하는 수, int
    :param b: 두 번째 더하는 수, int
    :return: 합계, int
    """
    return a + b

주요 특징:

Docstring은 __doc__에 저장되며 IDE, help(), 자동 문서 생성기에 접근 가능합니다.
타입 주석은 __annotations__를 통해 접근할 수 있으며, 코드 실행에는 영향을 미치지 않고 분석 용도로만 사용됩니다.
통합 적용하면 규모가 큰 지원과 새로운 프로그래머의 온보딩이 용이해집니다.

혼란을 주는 질문들.

타입 주석이 프로그램 실행에 영향을 미칠 수 있나요?

아니요. 타입 주석(type hints)은 인터프리터에 의해 실행 중에 검사되지 않으며, 오직 분석기 및 IDE, 그리고 문서 자동 생성 용도로만 사용됩니다. 이들은 런타임 오류를 초래하지 않으며 항상 선택적입니다.

타입 주석을 사용하여 매개변수 값을 제한할 수 있나요?

아니요. 예를 들어, x: int와 같이 타입을 지정해도 실제로는 다른 타입의 값을 전달하는 것을 금지하지 않습니다. 이를 위해 런타임 검사(assert/isinstance)를 사용할 수 있지만, type hints는 자동으로 검증되지 않습니다.

타입 주석 대신에 주석 # type: ...를 사용할 수 있습니까? 왜 필요한가요?

네, Python 2와의 호환성이나 오래된 코드베이스와의 호환성이 필요할 경우 가능합니다. 예를 들어:

def foo(x, y):     # type: (int, str) -> bool
    pass

이것은 mypy 및 유사한 도구가 현대적인 문법과 함께 인식하지만, 새로운 프로젝트에서는 표준 주석을 사용하는 것이 좋습니다.

일반적인 오류 및 안티 패턴

공개 함수 및 클래스의 docstring이 없거나 비어 있음.
잘못된 타입 지정 — 예를 들어, List 대신 list 또는 복잡한 컬렉션에서의 오타.
문서 업데이트 없이 type hints를 사용하거나 그 반대의 경우.

실제 사례

부정적인 케이스

대규모 프로젝트에서 함수는 docstring 및 type hints가 전혀 없으며, 개발자는 코드 학습 및 디버깅에 많은 시간을 소모하고, 종종 타입 및 입력 데이터의 의미를 혼동합니다.

장점:

시작할 때 코드 작성을 빨리 할 수 있습니다.

단점:

유지보수의 큰 어려움, 신규 직원 onboarding이 길어짐.
매개변수의 타입이 혼동되면 오류를 잡기 어렵습니다.

긍정적인 케이스

모든 공개 함수에는 자세한 docstring과 올바른 type hints가 있어 IDE와 분석기가 타입 오류를 신속하게 찾아내고 API 문서를 자동으로 생성할 수 있습니다.