python docstring 가이드

Docstring이란?

• class, module, function, method 정의 시 사용되는 python documentation string
• python 객체의 __doc__ attribute 또는 help() function을 통해 접근할 수 있다.
• 개발된 기능을 사용하거나 개발에 기여하는 다른 개발자들의 이해를 돕기 위해 작성되는 주석
• class, module, function, method의 첫 줄에 위치한다.
• 예시: pandas

Docstring의 다양한 포맷

One-Line Docstring

• ''' 또는 """으로 문장을 감싸 docstring을 만든다.

def square(a):
    '''Returned argument a is squared.'''
    return a**a

Multi-Line Docstring

• 여러 문장으로 된 docstring
• 보통 설명, parameter, return값으로 구성
• multi-line docstring에도 여러가지 format이 있다.
  • Sphinx Style
    • python documentation을 위해 만들어진 스타일.

        class Vehicle(object):
            '''
            The Vehicle object contains lots of vehicles
            :param arg: The arg is used for ...
            :type arg: str
            :param `*args`: The variable arguments are used for ...
            :param `**kwargs`: The keyword arguments are used for ...
            :ivar arg: This is where we store arg
            :vartype arg: str
            '''

            def __init__(self, arg, *args, **kwargs):
                self.arg = arg

            def cars(self, distance, destination):
                '''We can't travel a certain distance in vehicles without fuels, so here's the fuels

                :param distance: The amount of distance traveled
                :type amount: int
                :param bool destinationReached: Should the fuels be refilled to cover required distance?
                :raises: :class:`RuntimeError`: Out of fuel

                :returns: A Car mileage
                :rtype: Cars
                '''  
                pass

    - roles
        - param: 필수적으로 명시해야 한다.
        - type: sphinx data type for param
        - return: returned object
        - rtype: type of object retured
        
- Google Style
    - 더 쉽고 직관적이다.

        class Vehicles(object):
            '''
            The Vehicle object contains a lot of vehicles

            Args:
                arg (str): The arg is used for...
                *args: The variable arguments are used for...
                **kwargs: The keyword arguments are used for...

            Attributes:
                arg (str): This is where we store arg,
            '''
            def __init__(self, arg, *args, **kwargs):
                self.arg = arg

            def cars(self, distance,destination):
                '''We can't travel distance in vehicles without fuels, so here is the fuels

                Args:
                    distance (int): The amount of distance traveled
                    destination (bool): Should the fuels refilled to cover the distance?

                Raises:
                    RuntimeError: Out of fuel

                Returns:
                    cars: A car mileage
                '''
                pass

- Numpy Style
    - 구체적인 documentation에 유리한 문서화 스타일.

        class Vehicles(object):
            '''
            The Vehicles object contains lots of vehicles

            Parameters
            ----------
            arg : str
                The arg is used for ...
            *args
                The variable arguments are used for ...
            **kwargs
                The keyword arguments are used for ...

            Attributes
            ----------
            arg : str
                This is where we store arg,
            '''
            def __init__(self, arg, *args, **kwargs):
                self.arg = arg

            def cars(self, distance, destination):
                '''We can't travel distance in vehicles without fuels, so here is the fuels

                Parameters
                ----------
                distance : int
                    The amount of distance traveled
                destination : bool
                    Should the fuels refilled to cover the distance?

                Raises
                ------
                RuntimeError
                    Out of fuel

                Returns
                -------
                cars
                    A car mileage
                '''
                pass

참고

• https://www.datacamp.com/community/tutorials/docstrings-python