[파이썬 심화] 6. 문서화와 주석으로 꾸미기

프로그램을 실행해서 원하는 결과가 나와도 프로그램이 완성된 것은 아니다. 프로그램을 유지하려면 프로그램에 대한 설명이 필요하기 때문이다. 특히 모듈, 클래스, 함수에 관한 설명은 긴 문장으로 작성된다.

 

함수와 클래스의 문서화(docstring)

 파이썬 프로그램의 기준은 함수, 클래스, 모듈이다. 이 단위 기능을 설명하기 위해 문서화를 제공한다. 문서화로 작성된 것은 도움말 함수 help로 조회할 수 있다.

 

아무 모듈이나 import해보자.

import math

 

모듈의 문서화는 속성 __doc__에 저장되고 이를 다른 변수에 할당한 후 print로 출력할 수 있다. 

import math

a = math.__doc__
print(a)

[결과]
This module provides access to the mathematical functions
defined by the C standard.

 

문자열로 작성하면 문서화가 자동으로 만들어진다. 함수를 정의하며 여러 개의 문자열을 작성하고 그중에 어떤 문자열이 문서화로 들어가는지 확인해보자.

from typing import Type


def func(x, y):

    """ 첫 번째 매개변수 체크 """
    if not isinstance(x, int):
        raise TypeError("x가 정수가 아님")
    
    """ 두 번째 매개변수 체크 """
    if not isinstance(y, int):
        raise TypeError("y가 정수가 아님")

    return x + y

print(func.__doc__)

[결과]
 첫 번째 매개변수 체크

 

위의 결과를 통해 문서화는 항상 첫 번째에 작성해야 하는 것을 알 수 있다. 그리고 주석은 문서화 처리가 되지 않는다!

 

변수에 타입 힌트(type hint) 사용하기

 파이썬에도 변수에 특정 자료형을 타입으로 지정하는 방식을 제공한다. 하지만 변수를 정의하는 것이 아닌 변수에 관한 주석을 추가하는 기능이다.

 

빈 셀에 변수 이름 x 다음에 콜론을 쓰고 int 클래스 이름을 지정한 후에 실행하면 예외가 발생하지 않지만 이 변수를 조회하면 예외가 발생한다. 타입 힌트만 지정했을 뿐 실제 변수 x는 정의되지 않았기 때문이다.

x : int

try: 
    print(x)
except Exception as e:
    print(e)
    
[결과]
name 'x' is not defined

y : int
y = 100

try: 
    print(y)
except Exception as e:
    print(e)
    
[결과]
100

 

이는 함수 내부에 지역 변수를 정의할 때도 타입 힌트를 지정할 수 있다.

def add(x, y):
    z : int
    z = x + y
    return z

print(add(10, 10))

[결과]
20

 

처음에 타입 헌트가 왜 필요하나 싶었지만 찾아보니 이유가 있었다.

타입에 대한 파이썬의 유연함은 일회성 스크립트나 소규모의 애플리케이션을 빠르게 개발할 때는 큰 장점으로 작용합니다. 하지만 애플리케이션이 규모가 커지게 되면 이러한 파이썬의 다이나믹함이 치명적인 버그로 이어질 확률이 높아지게 되며 애플리케이션 안정성에 위험 요소가 되기도 합니다. 따라서 중규모 이상의 파이썬 프로젝트에서는 소위 타입 힌팅(type hinting)이라는 개발 프로세스를 도입하여 사용하는 경우가 많습니다.

타입 힌팅(type hinting)은 말 그대로 파이썬 코드를 작성할 때 타입에 대한 메타 정보를 제공하는 것입니다. 파이썬에 타입 힌팅이 추가되기 전에는 타입을 표시하려면 주석(comments)을 이용했어야 했었습니다. 이 방법은 코드를 읽는 개발자에게는 약간의 도움이 될지는 모르겠으나 정해진 표준이 없었고 일반 주석과 구분이 어려웠습니다.

출처 : https://www.daleseo.com/python-type-annotations/

파이썬 타입 어노테이션/힌트

 

참고

• 한권으로 개발자가 원하던 파이썬 심화 A to Z, 문용준/문성혁 저