IT/기초 지식
docstring의 세 가지 스타일
개발자 두더지
2022. 4. 13. 17:08
728x90
이번 포스팅에서는 docstring 작성에 주로 사용되는 세 가지 스타일 reStructuredText, Google style, Numpy style에 대해서 간략하게 알아보고자한다.
reStructuredText
def func(arg1, arg2, arg3):
"""Hello, func
Lorem ipsum dolor sit amet,
:param string arg1: First argument
:param arg2: Second argument
:type args2: list[int]
:param arg3: Third argument
:type args3: dict[str, int]
:return: Return value
:rtype: str or None
:raises ValueError: if arg1 is empty string.
"""- param, parameter, arg, argument, ket, keword : 인수의 설명
- type : 인수의 데이터 형
- raises, raise, except, exception : 예외(언제 예외가 발생하는가?)를 정의
- var, ivar, cvar : 변수의 설명
- vartype : 변수의 데이터형
- returns, return : 반환 값에 대한 설명
- rtype : 반환값의 데이터 형
Google style
def func(arg1, arg2, arg3):
"""Hello, func
Lorem ipsum dolor sit amet,
Args:
arg1 (str): First argument
arg2 (list[int]): Second argument
arg3 (dict[str, int]): Third argument
Returns:
str or None: Return value
Raises:
ValueError: if arg1 is empty string.
"""- Args: 각 변수의 목록을 기재. 이름뒤에 클론과 스페이스를 구분해 설명은 작성한다. 설명이 80개의 문자이내로 끝나지 않은 경우 다음행에 띄어쓰기 2개나 4개로 구분해서 계속해서 작성한다.
- Returns: 데이터형과 반환 값의 시멘틱스를 설명한다. 함수에서 None만 반환되는 경우, 이 섹션을 불필요하다.
- Raises: 인터페이스와 관련된 모든 예외 목록을 기재한다.
섹션 목록
- Args (alias of Parameters)
- Arguments (alias of Parameters)
- Attributes
- Example
- Examples
- Keyword Args (alias of Keyword Arguments)
- Keyword Arguments
- 메소드
- Note
- Notes
- Other Parameters
- Parameters
- Return (alias of Returns)
- Returns
- Raises
- References
- See Also
- 과제
- Warning
- Warnings (alias of Warning)
- Warns
- Yield (Yields의 다른 이름)
- Yields
Numpy style
def func(arg1, arg2, arg3):
"""Hello, func
Lorem ipsum dolor sit amet,
Parameters
-------
arg1 : str
First argument
arg2 : list[int]
Second argument
arg3 : dict[str, int]
Third argument
Returns
-------
str or None
Return value
Raises
-------
ValueError
if arg1 is empty string.
"""자세한 내용은 공식 문서를 확인하길 바란다.
참고자료
728x90