Docstring & 어노테이션

1. Docstring

 

docstring은 모듈, 함수, 클래스 또는 메소드 정의의 첫 번째 명령문으로 발생하는 문자열 리터털로 소스 코드에 포함된 문서(documentation)라고 할 수 있다. docstring은 기본적으로 리터럴 문자열이며, 로직의 일부분을 문서화하기 위해 코드 어딘가에 배치된다. 

 

특히 문서라는 단어에 주목해보면 이는 주석과는 확실히 다르다는 것이다. 주석을 다는 습관은 좋지 않은 것이다. 

• 주석을 다는 것은 코드로 아이디어를 제대로 표현하지 못했음을 의미한다.
• 코드의 변경에 따라 주석도 주기적으로 업데이트 해줘야하지만 대부분의 사용자가  이를 간과하거나 주석을 먼저 확인 한 후에 코드의 동작을 이해하는 것은 오해를 불러일으킨다.

 

1-1. Docstring 사용법. 

 

def my_function():
	'''
    임의의 계산 수행
    
	'''
    return result

docstring은 코드에서 분리되거나 독립된 것이 아니라 코드의 일부가 되어 접근할 수 있게 하고, __doc__ 속성이 함수에 추가된다.

 

my_function.__doc__

>>>'임의의 계산 수행'

help(my_function)
//help 함수를 통해서 docstring의 내용을 확인할 수도 있다.

즉 런타임 중에 접근하고 소스 코드에서 docstring 내용을 추가, 수정하거나 컴파일 하는 것이 가능하다.

 

---

 

2. 어노테이션

 

어노테이션의 사전적 의미는 "주석"이다. 이는 코드 사용자에게 함수의 인자로 어떤 값이 와야 하는지 힌트를 주는 것이다. 어노테이션을 사용하여 변수의 예상 타입을 지정할 수 있고, 실제로는 타입 뿐만 아니라 변수를 이해하는데 도움이 되는 어떤 형태의 메타 데이터라도 지정할 수 있다.

 

def locate(latitude: float, longtitude: float) -> Point:

	'''맵에서 좌표에 해당하는 객체를 검색하는 함수'''
    
    ~~함수 코드~~

이 함수의 인자인 latitude와 longtitude는 float 타입의 변수이며, 이를 통해 함수 사용자는 예상되는 타입을 알 수 있다. 하지만 파이썬 자체에서 타입 자체를 검사하거나 강제하지 않기 때문에 타입이 달라도 오류는 발생하지 않는다.

 

locate.__annotations__

>>> {'latitude':float, 'longtitude':float, 'return':__main__.Point}

어노테이션을 사용하면 __annotations__ 이라는 특수한 속성이 생긴다. 이 속성은 어노테이션의 이름과 값을 매핑한 사전 타입의 값이며 함수에 대한 정보를 쉽게 파악할 수 있다.

 

---

 

어노테이션과 Docstring 중에 무엇을 사용해야 할까?

 

어노테이션이 소개되기 이전부터 함수의 파라미터 또는 속성의 타입을 문서화 할때 docstring을 많이 사용했기 때문에 이제는 docstring 대신에 어노테이션을 사용해야 하는 것이냐는 질문이 나오기도 한다. 

 

docstring에 포함된 정보들은 어노테이션으로 이동시켜 담을 수 있는 것은 사실이다. 하지만 docstring을 통해 보다 나은 문서화를 위한 여지를 남겨두어 동적 데이터 타입과 중첩 데이터 타입의 경우 예상 데이터의 예제를 제공하여 어떤 형태의 데이터를 다루는가에 대해 정보를 제공하는 것이 좋다.

 

즉, 어노테이션과 Docstring은 서로 보완적인 개념으로 사용하는 것이 가장 좋다.