파이썬 문서화하기 - docstring

소스코드는 한번 짜면 끝이 아닙니다. 프로그램이 문제없이 돌아가기 위해서는 유지보수를 계속 해야합니다.

유지보수를 위해서는 네이밍 규칙 정하기, 간결한 코드 작성, 버전 관리 툴 사용등과 같은 방법이 있습니다.

하지만 그 무엇보다도 코드가 어떤 동작을 하는지, parameter은 무엇이고 return 값은 무엇인지에 대해서 문서화를 해야 새로운 팀원이 코드를 봐도 빠르게 이해하고 팀에 녹아들 수 있을것입니다.

저는 개발자가 많은 프로젝트에 참여한 경험이 없어서, 이때까지 문서화에 소홀히해왔습니다.

최근 파이썬으로 진행한 프로젝트가 커지면서 문서화가 필요하다고 생각해서 공부하게 되었고 그 내용을 포스팅으로 정리했습니다.

 

1. Docstring 위치

함수 선언부 바로 아래에 따옴표를 사용해서 작성할 수 있습니다.

def get_arr_size(arr):
    """
    여기에 함수를 설명합니다.
    """
    size = len(arr)
    return size

 

2. Docstring 작성방법

위에서 선언한 get_arr_size는 함수 이름 그대로 parameter로 들어온 arr의 사이즈를 반환하는 함수입니다.

함수를 문서화 할 때는, 1. 함수 기능 설명 2. parameter 3. return 값을 작성해야합니다.

def get_arr_size(arr):
    """
    arr의 size를 반환한다.
    :param arr: list
    :return size: int
    """
    size = len(arr)
    return size

 

3. Docstring 확인하기

gaussian_filter.py 파일에 get_gaussian_filter_1d 함수를 아래와 같이 선언하고, docstring.py에서 함수의 docstring을 가져와봤습니다.

# gaussian_filter.py
#-*- coding:utf-8 -*-

import numpy as np
import math

def get_gaussian_filter_1d(size, sigma):
    """
    1D 가우시안 필터를 생성한다.
    :param size: int 커널 사이즈
    :param sigma: float
    :return kernel: np.array
    """
    assert size%2==1, "Filter Dimension must be odd" # filter size는 무조건 odd여야한다
    arr = np.arange(math.trunc(size/2)*(-1), math.ceil(size/2)+1 ,1) # 중심으로 부터의 거리가 값인 배열 생성
    kernel_raw = np.exp((-arr*arr)/(2*sigma*sigma)) # 가우시안 필터 공식
    kernel = kernel_raw/kernel_raw.sum() # 정규화
    return kernel

# docstring.py
#-*- coding:utf-8 -*-
from gaussian_filter import get_gaussian_filter_1d

print(get_gaussian_filter_1d.__doc__)

결과 화면

파이썬으로 개발하다 보면 라이브러리의 사용법을 몰라서 에러가 나는 경우가 많습니다.

이 때 docstring을 확인하면 개발할 때 무엇이 문제인지 빠르게 확인할 수 있습니다.

Terminal에서 원하는 패키지를 import 한 뒤에 help(함수이름)으로 docstring을 확인할 수 있습니다.

터미널 화면

help(np.arange)를 하면 다음과 같이 docstring 만 보여줍니다.

터미널 화면

위 화면에서 이전으로 돌아가고 싶다면 q를 누르면 됩니다.

 

유명한 패키지의 docstring을 보면서 문서화란 이런거다!를 느끼고 있습니다.

좋은 개발자가 되기 위해서는 문서화를 위한 글도 잘 써야하는거겠죠ㅠㅠ

개발자가 될 때 까지 화이팅하겠습니다.

---

잘못된 내용이 있다면 언제든지 댓글이나 메일로 알려주시면 감사하겠습니다.

이 포스팅이 도움이 되었다면 공감 부탁드립니다.

궁금한 점은 언제든지 댓글 남겨주시면 답변해드리겠습니다:D