파이썬 교육 챕터 40 함수 독스트링과 주석

by

함수 독스트링(Docstring)과 주석: 좋은 함수 문서화의 시작

1. 서론: 코드는 설명이 필요하다

지금까지 우리는 파이썬의 기본적인 문법과 자료 구조, 제어문, 그리고 함수를 정의하고 사용하는 방법을 배웠습니다. 함수는 코드의 재사용성을 높이고 프로그램을 모듈화하는 데 필수적인 도구입니다. 하지만 아무리 잘 작성된 함수라도 그 기능과 사용법이 명확하게 설명되어 있지 않다면, 다른 개발자(또는 미래의 자신)가 이해하고 사용하기 어려울 수 있습니다. 이때 필요한 것이 바로 ‘문서화(Documentation)’입니다. 파이썬에서는 함수를 문서화하는 데 ‘독스트링(Docstring)’과 ‘주석(Comment)’이라는 두 가지 주요 도구를 제공합니다. 우리는 이미 주석의 중요성에 대해 간략히 다루었지만, 이 챕터에서는 특히 함수에 초점을 맞춰 독스트링의 개념과 작성법, 그리고 주석과의 차이점 및 좋은 함수 문서화를 위한 원칙에 대해 깊이 있게 알아보겠습니다. 함수를 효과적으로 문서화하는 능력은 여러분의 코드를 더욱 전문적이고 협업에 용이하게 만들 것입니다.

2. 독스트링(Docstring)이란 무엇인가?

독스트링은 함수, 클래스, 모듈의 정의 바로 아래에 위치하는 삼중 따옴표("""...""" 또는 '''...''')로 둘러싸인 문자열입니다. 독스트링은 파이썬 인터프리터에 의해 특별하게 인식되며, 코드의 문서화에 사용됩니다. help() 함수나 IDE의 도움말 기능을 통해 독스트링에 접근할 수 있습니다.

2.1. 독스트링의 역할

  • 함수의 목적 설명: 함수가 무엇을 하는지, 어떤 문제를 해결하는지 설명합니다.
  • 매개변수 설명: 함수가 어떤 매개변수를 받는지, 각 매개변수의 의미와 자료형을 설명합니다.
  • 반환 값 설명: 함수가 어떤 값을 반환하는지, 반환 값의 의미와 자료형을 설명합니다.
  • 예외 처리 설명: 함수가 발생시킬 수 있는 예외(오류)에 대해 설명합니다.
  • 사용 예시: 함수를 어떻게 사용하는지 간단한 예시 코드를 제공합니다.

2.2. 독스트링 작성 예시

def calculate_rectangle_area(width, height):
    """직사각형의 면적을 계산하여 반환하는 함수입니다.

    이 함수는 주어진 너비와 높이를 곱하여 직사각형의 면적을 계산합니다.
    너비와 높이는 양의 숫자여야 합니다.

    Args:
        width (float or int): 직사각형의 너비. 양수여야 합니다.
        height (float or int): 직사각형의 높이. 양수여야 합니다.

    Returns:
        float or int: 계산된 직사각형의 면적.
                      너비나 높이가 음수일 경우 None을 반환합니다.

    Raises:
        ValueError: 너비나 높이가 숫자가 아닐 경우 발생합니다.

    Examples:
        >>> calculate_rectangle_area(5, 10)
        50
        >>> calculate_rectangle_area(2.5, 4)
        10.0
        >>> calculate_rectangle_area(-1, 5)
        None
    """
    if not isinstance(width, (int, float)) or not isinstance(height, (int, float)):
        raise ValueError("너비와 높이는 숫자여야 합니다.")
    if width < 0 or height < 0:
        return None
    return width * height

# 독스트링 확인 방법
print(calculate_rectangle_area.__doc__)
help(calculate_rectangle_area)

# 출력 (help()는 더 상세한 형식으로 출력됩니다):
# 직사각형의 면적을 계산하여 반환하는 함수입니다.
# 
#     이 함수는 주어진 너비와 높이를 곱하여 직사각형의 면적을 계산합니다.
#     너비와 높이는 양의 숫자여야 합니다.
# 
#     Args:
#         width (float or int): 직사각형의 너비. 양수여야 합니다.
#         height (float or int): 직사각형의 높이. 양수여야 합니다.
# 
#     Returns:
#         float or int: 계산된 직사각형의 면적.
#                       너비나 높이가 음수일 경우 None을 반환합니다.
# 
#     Raises:
#         ValueError: 너비나 높이가 숫자가 아닐 경우 발생합니다.
# 
#     Examples:
#         >>> calculate_rectangle_area(5, 10)
#         50
#         >>> calculate_rectangle_area(2.5, 4)
#         10.0
#         >>> calculate_rectangle_area(-1, 5)
#         None

2.3. 독스트링 스타일

독스트링을 작성하는 표준화된 스타일은 여러 가지가 있습니다. 가장 널리 사용되는 스타일은 다음과 같습니다.

  • Google Style: 간결하고 명확한 설명을 선호하며, Args:, Returns:, Raises: 등의 섹션을 사용합니다.
  • NumPy/SciPy Style: 과학 계산 라이브러리에서 많이 사용되며, 더 상세한 섹션(Parameters, Returns, See Also, Notes, Examples 등)을 가집니다.
  • reStructuredText Style: Sphinx와 같은 문서화 도구에서 사용되는 마크업 언어 기반 스타일입니다.

어떤 스타일을 사용하든 일관성을 유지하는 것이 중요합니다. IDE나 린터(Linter)는 이러한 스타일 가이드를 따르도록 도와줍니다.

3. 주석(Comment)과 독스트링의 차이점

주석과 독스트링은 모두 코드에 설명을 추가하는 역할을 하지만, 그 목적과 사용 방식에서 중요한 차이가 있습니다.

특징 주석 (Comment) 독스트링 (Docstring)
기호 # """...""" 또는 '''...''' (함수/클래스/모듈 정의 바로 아래)
목적 코드의 특정 부분에 대한 간략한 설명, 임시 비활성화, 개발자 메모 함수/클래스/모듈의 전반적인 목적, 사용법, 매개변수, 반환 값 등 공식 문서화
접근 파이썬 인터프리터가 무시, 코드 편집기에서만 확인 __doc__ 속성, help() 함수, IDE의 도움말 기능으로 접근 가능
위치 코드 라인 위, 뒤, 또는 독립적인 줄 함수/클래스/모듈 정의의 첫 번째 문장으로 위치

예시:

def calculate_sum(a, b):
    # 이 함수는 두 숫자의 합을 계산합니다. (주석)
    # TODO: 나중에 음수 처리 로직 추가 (개발자 메모)
    """두 숫자의 합을 반환합니다.

    Args:
        a (int): 첫 번째 숫자
        b (int): 두 번째 숫자

    Returns:
        int: 두 숫자의 합
    """
    result = a + b # 덧셈 연산 수행 (주석)
    return result

4. 좋은 함수 문서화를 위한 원칙

함수를 효과적으로 문서화하는 것은 코드의 품질을 높이고 협업을 용이하게 하는 데 매우 중요합니다. 다음은 좋은 함수 문서화를 위한 몇 가지 원칙입니다.

4.1. 독스트링은 필수, 주석은 보조

모든 함수(특히 공개적으로 사용될 함수)에는 독스트링을 작성하는 것이 좋습니다. 독스트링은 함수의 ‘공식적인’ 설명서 역할을 합니다. 주석은 독스트링으로 설명하기 어려운 코드의 특정 부분이나 복잡한 로직에 대한 보조적인 설명을 제공하는 데 사용합니다.

4.2. 코드가 ‘무엇을’ 하는지보다 ‘왜’ 하는지를 설명하라 (독스트링)

독스트링은 함수가 어떤 작업을 수행하는지, 어떤 문제를 해결하는지, 어떤 가정을 하는지 등 함수를 사용하는 사람이 알아야 할 ‘큰 그림’을 설명해야 합니다. 코드만으로도 명확한 부분에 대한 장황한 설명은 피합니다.

4.3. 주석은 코드의 의도를 설명하라

주석은 코드 라인이나 블록이 ‘왜’ 그렇게 작성되었는지, 어떤 의도를 가지고 있는지, 어떤 특별한 고려 사항이 있는지 등 코드만으로는 알기 어려운 배경 지식을 설명하는 데 집중합니다.

4.4. 최신 상태를 유지하라

코드와 문서화(독스트링, 주석)는 항상 일치해야 합니다. 코드가 변경되면 관련 독스트링과 주석도 함께 업데이트하는 습관을 들여야 합니다. 오래된 문서화는 잘못된 정보를 제공하여 혼란을 야기합니다.

4.5. 간결하고 명확하게 작성하라

독스트링과 주석 모두 핵심 내용을 간결하고 명확하게 전달해야 합니다. 장황하거나 모호한 표현은 피하고, 필요한 정보만을 정확하게 기술합니다.

4.6. PEP 8 및 독스트링 스타일 가이드 준수

파이썬 코딩 스타일 가이드인 PEP 8은 주석 작성에 대한 권장 사항을 제시합니다. 또한, 독스트링 스타일(Google, NumPy 등)을 선택하여 일관성 있게 작성하면 문서화 도구와의 연동도 용이해집니다.

5. 결론: 소통하는 코드, 성장하는 개발자

이 챕터를 통해 여러분은 파이썬 함수의 독스트링과 주석을 사용하여 코드를 효과적으로 문서화하는 방법에 대해 깊이 있게 학습했습니다. 독스트링이 함수의 공식적인 설명서 역할을 하며 help() 함수를 통해 접근 가능하다는 점, 그리고 주석이 코드의 특정 부분에 대한 보조적인 설명을 제공한다는 차이점을 이해했습니다. 또한, 좋은 함수 문서화를 위한 원칙들을 살펴보았습니다.

함수를 잘 정의하고, 매개변수를 명확히 하며, 반환 값을 적절히 활용하는 것만큼이나, 함수를 잘 문서화하는 것은 매우 중요합니다. 잘 문서화된 코드는 다른 개발자와의 협업을 원활하게 하고, 미래의 자신을 위한 훌륭한 참고 자료가 됩니다. 이는 여러분의 코딩 실력뿐만 아니라, 개발자로서의 전문성과 소통 능력을 한 단계 더 높여줄 것입니다.

이제 여러분은 파이썬 함수의 모든 기본적인 개념을 마스터했습니다. 다음 챕터부터는 파이썬의 핵심 개념 중 하나인 ‘모듈(Module)’의 개념과 import 문에 대해 본격적으로 학습할 것입니다. 모듈은 코드를 파일 단위로 분리하여 관리하고 재사용하는 데 필수적이므로, 오늘 배운 함수 문서화 기술을 활용하여 여러분이 작성하는 모든 함수에 독스트링과 필요한 주석을 추가하는 습관을 들이세요!

파이썬 교육 챕터 40 함수 독스트링과 주석