파이썬 Docstring / Annotation

파이썬 Docstring과 Annotation

파이썬 어노테이션 (Annotation)

파이썬 3에는 유형 힌트를 줄 수 있는 어노테이션이라는 개념을 제공합니다. 어노테이션을 사용하는 데 있어서 유의해야 할 사항은 총 3가지가 있습니다.

 

첫째, 어노테이션은 사용해도 되고 사용하지 않아도 되는 선택적입니다.

둘째, 격식이 없습니다.

 

어노테이션은 함수를 정의하는 데 있어 파라미터의 와 반환 값 유형의 힌트를 주는 역할을 합니다. 

 

def captain_bin_func(in_par:str="blog") -> str:
	return "Captain BIN " + in_par

 

captain_bin_func라는 함수를 정의하는 간단한 예제 코드를 살펴보겠습니다. 함수 파라미터로 쓰이는 in_par변수에 :str 이 붙어 있습니다. 이 의미는 in_par 파라미터가 문자열을 입력받는다는 것을 힌트로 주고 있습니다. 또한 함수 마지막 부분에 -> str의 의미는 함수에서 리턴하는 값이 문자열이라는 것을 힌트로 주고 있습니다.

 

 어노테이션은 격식이 없으며 사용해도 되고 사용하지 않아도 되는 선택적이라 말씀드렸습니다. 하지만 사용하게 되면 반드시 파이썬에서 정의하는 자료형을 사용해 주어야 합니다. 스트링이라면 str을 정수형이라면 int를 딕셔너리라면 dict와 같이 선언해 주셔야 합니다. 만약 파이썬에서 정의된 어노테이션을 사용하지 않는다면 NameError가 발생합니다.

 

그렇다면 이 어노테이션은 왜 사용할까요? 그 이유는 밑에 Docstring의 설명을 보시면 이해하실 수 있습니다.

 

 

파이썬 독스트링(Docstring)

파이썬에서는 특이한 자료형이 존재합니다. 바로 docstring입니다. 이 docstring은 작은따옴표(') 혹은 큰따옴표(") 세 개를 사용하여 문자열을 표현하는 자료형입니다. 참고로 다른 프로그래밍에서는 "heredoc" 이라고도 합니다.

 

문자열을 여러 줄에 걸쳐 사용할 때 편리하게 사용되는 자료형이지만 이 자료형의 또 다른 용도는 바로 docstring으로 사용할 수 있습니다. docstring은 함수 선언 후 바로 문자열을 사용하게 되면 해당 함수가 help() 호출을 받게 되면 이 docstring을 출력해 줍니다.

 

def captain_bin_func(in_par:str="blog") -> str:
	"""captain_bin_func Help Message
Usage:
	Just call."""
    
	return "Captain BIN " + in_par

 

위와 같이 함수를 정의하고 help함수로 captain_bin_func를 호출해 보겠습니다.

 

파이썬 독스트링, 어노테이션 출력 결과

 

help() 함수 수행 결과에 docstring으로 추가한 문자열을 확인할 수 있습니다.

 

또한 이 예제는 위에서 어노테이션의 코드에 docstring만 추가하였습니다. 수행 결과 값 중 함수 정의가 보이시나요? 

 

만약 어노테이션이 없다고 가정하면 함수를 사용하는 데 있어서 입력 값은 무엇인지 출력은 어떤 형태인지 docstring에 서술하거나 이마저도 없다면 함수가 정의되어 있는 코드를 찾아 읽어야 하는 불상사가 생길 수 있습니다.

 

물론 본인이 작성한 함수를 바로 사용한다면 문제 될 것이 없습니다. 하지만 약 3개월이 흐른 뒤 다시 코드를 보게 된다면 그때도 과연 문제가 되지 않을까요?

 

파이썬 어노테이션과 독스트링의 큰 공통점은 바로 프로그래머의 선택 사항이라는 것입니다.

 

하지만 어노테이션이 정의된 함수는 개발 툴에서 자동완성 기능을 사용할 수 있고 몇 개월 뒤 기억 저편에 있는 본인이 만든 코드를 분석하는 본인을 위해서나 남을 위해서 어노테이션과 독스트링은 선택 사항이 아닌 필수 사항이지 않을까 싶습니다.