Function 에 documentation 하는 방법

코드를 이해하고 사용하기 쉽게 만들어주는 주석은 간과하기 쉽습니다.

 

특히나 팀으로 하지 않고 혼자하는 경우는 더 하지요.

 

하지만 점점 더 복잡해질수록 본인이 만든 코드/ 스크립트라고 해도 이해하는데 시간이 걸리거나

 

단번에 확인하여 사용할수 없는 경우도 충분히 많습니다.

 

그중에서 만들어진 함수 코드에 이해하기 쉬운 글을 다는 방법에 대해서 이야기 해볼까 합니다.

 

외국 자료에서는 doc-strings (documentation strings)이라는 표현을 주로 쓰는 군요.

 

일단 예를 한번 볼까요?

 

백문이 불여일견.

 

def population_density(population, land_area):
    """Calculate the population density of an area. """
    return population / land_area

이제 Docstrings라고 표현하겠습니다.

 

Docstrings는 """  """" 요 사이에 둘러 싸여있는 것을 확인 할수 있습니다.

이제 줄별로 알아봅시다.

 

첫째줄에는 함수의 목적에 대해서 간단히 서술해놓습니다.

 

복잡하지 않은 경우는 함수 목적에 대해서 서술만으로도 충분하겠군요.

 

하지만 복잡하고 중요할 경우에는 좀 더 정보를 넣어주는게 맞지 않을까요?

 

아래에 추가적인 예시를 보겠습니다.

 

def population_density(population, land_area):
    """Calculate the population density of an area.

    INPUT:
    population: int. The population of that area
    land_area: int or float. This function is unit-agnostic, if you pass in values in terms
    of square km or square miles the function will return a density in those units.

    OUTPUT: 
    population_density: population / land_area. The population density of a particular area.
    """
    return population / land_area

Function에 입력되는 변수에 대한 설명과 Return하는 출력값에 대한 설명을 추가했네요.

 

필요에 따라 이러한 방식으로 추가 정보를 기입하는 것도 좋은 방법이 되겠습니다.