[Python 기초] 주석(Docstring) 작성 스타일

Python 기초 정리 세 번째 시간. 

 

Python 코드를 작성하면서 주석은 중요하다. 실제로 일을 하다 보면, 내가 작성한 코드를 남이 보게 되는 경우가 꽤나 발생하기 때문이다. 지금까지는 주먹구구식으로, 내 맘대로 Python 코드의 주석을 작성해 왔지만, 오늘부터는 한 가지 스타일로 밀고 나가려고 한다.

 

 

주석을 쓰면 좋은 점

 

예를 들어서, 내가 함수 안에, 정확히는 def 로 함수를 정의하고 바로 아래쪽에 위와 같이 주석을 작성했다고 치자. 이 함수는 name이라는 arguments를 받아서 별표를 덕지덕지 붙여서 출력하는 함수이다.

 

함수 위에 마우스 커서를 올리면, 이렇게 주석으로 작성한 내용이 보이게 된다.

 

 

만약 메서드나 함수를 통해서 원하는 함수의 주석을 살펴보고 싶다면 두 가지가 가능하다.

 

1. 함수.__doc__ 로 __doc__ 메서드 사용하기

2. help 함수 사용하기

 

 

위 코드의 실행 결과는 아래와 같다.

 

 

위 쪽이 __doc__ 메서드를 쓴 결과이고, 아래 쪽이 help 함수를 사용한 결과이다.

 

이런 기능이 있는 줄도 몰랐는데 .. 협업할 때 도움이 꽤나 될 것 같다 ㅎㅎ

 

 

주석 스타일

주석 스타일은 생각보다 꽤나 다양하다. javadoc style, reST style, Google style, Numbydoc style 등..

 

예를 들어서 javadoc style은 이런 식으로 주석을 작성한다고 한다.

 

1. javadoc style

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

 

2. Google style

"""
This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

 

3. Numpydoc style

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
    the 1st param name `first`
second :
    the 2nd param
third : {'value', 'other'}, optional
    the 3rd param, by default 'value'

Returns
-------
string
    a value in a string

Raises
------
KeyError
    when a key error
OtherError
    when an other error
"""

 

Numpydoc style이 Data Science style이라고 해서 앞으로는 저렇게 한 번 작성을 해보려고 한다.

 

보니까 무엇을 이야기할 것인지 쓰고, '----'와 같은 걸로 구분을 하는 스타일인 것 같다.

 

def print_name(name: str):
    """
    이 함수는 name을 입력 받아서 이름을 멋지게 출력하는 함수입니다.
    
    Parameter
    -------
    first : string
        출력하고자 하는 string, parameter name은 'name' 입니다.
    
    
    Return
    ------
    None 
        단, print문을 통해서 이름을 출력합니다.
        
    
    KeyError
    ------
    특별한 Error 처리는 없음.
    """
    return print(f"당신의 이름은 ★{name}★이군요! ☆정★말☆ 멋집니다.!")

print_name('김철수')

 

아까 재미로 만든 함수에 Numpydoc style로 한 번 주석을 작성해 보았다.

 

 

와 .. 함수에서 hover를 하니까 이렇게 나타난다 .. VS Code가 이런 것까지 인식을 하는 줄은 몰랐는데, 신기하다. 이 글을 작성하면서 발견했다..

 

 

끝.