[클린 코드] 2. docstring과 annotation을 이용한 코드 문서화

---

내가 작성한 파이썬(Python) 코드, 좀 더 구체적으로 말하면 클래스나 함수를 다른 엔지니어가 사용하려고 할 때 그 함수에 대한 입출력 정보, 동작 방식을 확인할 수 있어야 한다. 이때 사용하는 것이 docstring과 annotation이다. 이번 포스팅에서는 docstring과 annotation에 대해서 알아보려고 한다.

---

   docstring과 annotation을 이용한 코드 문서화

1) docstring

docstring은 함수, 클래스에 대한 사용법, 입출력 정보 등을 문서화할 수 있는 기능이다. docstring은 어떤 정해진 형식은 없으나 대체로 함수 설명, 입력값 정보, 출력값 정보, 그리고 사용법 예제 순으로 정리하는 것 같다. docstring은 함수 또는 클래스 내에 홑따옴표(또는 큰따옴표)를 이용하여 멀티 라인으로 작성한다.

 

아래 코드는 배열의 평균을 계산하는 mean 함수 내부에 docstring을 작성한 것이다.

 

def mean(data):
    '''
    Decription
    calculate sample mean
    
    Parameters
    data : like array
    
    Return
    number
    
    Example
    data = [1,2,3,4,5]
    print(mean(data))
    '''
    return sum(data)/len(data)

 

이렇게 만든 docstring은 __doc__를 이용하여 내용을 확인할 수 있다.

 

print(mean.__doc__)

 

 

만약 함수(또는 클래스) docstring이 없다면 None을 출력한다.

def say_hello():
    return 'Hello~'

print(say_hello.__doc__) ## docstring이 없으므로 None을 출력한다.

 

---

2) annotation

docstring의 단점은 함수 내부에 수동으로 내용을 설정해야한다는 점인데 만약 간단한 함수에서도 docstring을 사용하면 매우 번거로우며 코딩하는 사람을 지치게 할 것이다. 이런 경우에는 간단히 입출력 정보만 간단하게 적어두는 것이 더 효과적이다. 이러한 필요에 의해서 나온 것이 annotation이다. 

 

annotation은 변수의 타입 또는 함수의 입출력 타입을 표현하는 방식이며 강제성을 띄지 않는다. 즉, 변수에 다른 타입이 들어와도 그것 때문에 에러가 발생 안한다는 것이다. 이제 변수 선언과 함수 입출력의 annotation 방법을 알아보자.

a. 변수 선언

변수 선언을 위한 annotation 방법을 알아보자. annotation은 변수명 다음에 콜론 ':'을 쓰고 타입 객체를 넣어준다. 이때 등호 '='를 이용하여 값을 설정할 수도 있고 안할 수도 있다.

 

int_var : int ## 타입 설정만하고 값을 지정안한 경우
str_var : str = 'Hello' ## 타입과 값을 모두 지정한 경우

 

이때 int_var에는 값을 지정하지 않았음에도 실행은 된다. str_var를 출력하면 정상적으로 'Hello'가 나오는 것을 알 수 있다.

 

 

하지만 int_var를 출력하면 NameError가 발생한다.

 

 

b. 함수 입출력

annotation은 입력 타입을 정할 때에는 콜론 ':'을 쓰고 출력 타입을 정할 때에는 화살표 '->'을 사용한다.

 

def add(x : int, y : int) -> int:
    return x+y

 

앞에서도 말했지만 annotation은 강제성을 띄지 않아서 실제로 int 대신 float을 입력값으로 전달해도 add 함수는 동작한다.

 

add(1.2, 3.4) ## 실제 int 타입이 아닌 float 타입이 들어와도 함수는 실행된다.

 

 

지난 포스팅에서 다룬 mypy와 같은 모듈을 이용하면 특정 함수의 입출력 정보가 annotation에 맞는지 검사할 수 있다.

---