문서화

Python으로 배우는 소프트웨어 공학 원칙

Adam Spannbauer

Machine Learning Engineer at Eastman

Python에서의 문서화

주석

# x의 제곱

독스트링

    """x의 제곱을 반환

    :param x: 제곱할 수
    :return: x의 제곱

    >>> square(2)
    4
    """

주석

#これは有効なコメントです
x = 2

y = 3  # 이것도 유효한 주석입니다

# 소스 코드를 보지 않으면 보이지 않습니다

# 미래의 협업자 여러분 안녕하세요!!

효과적인 주석

무엇을 적는 주석

# people을 5로 정의
people = 5

# people에 3을 곱함
people * 3

왜를 적는 주석

# 파티 참석자는 5명
people = 5

# 1인당 피자 3조각 필요
people * 3

독스트링

def function(x):
    """함수의 상위 수준 설명

    함수에 대한 추가 상세

독스트링

def function(x):
    """함수의 상위 수준 설명

    함수에 대한 추가 상세

    :param x: 매개변수 x 설명
    :return: 반환값 설명

Flask 패키지의 독스트링으로 생성된 웹페이지 예시.

독스트링

def function(x):
    """함수의 상위 수준 설명

    함수에 대한 추가 상세

    :param x: 매개변수 x 설명
    :return: 반환값 설명

    >>> # 함수 사용 예시
    예시 사용의 예상 출력
    """
    # function code

독스트링 예시

def square(x):
    """x의 제곱을 반환

    :param x: 제곱할 수
    :return: x의 제곱

    >>> square(2)
    4
    """
    # `x * x`가 `x ** 2`보다 빠름
    # 참고: https://stackoverflow.com/a/29055266/5731525
    return x * x

독스트링 출력 예시

help(square)

square(x)
    x의 제곱을 반환

    :param x: 제곱할 수
    :return: x의 제곱

    >>> square(2)
    4

Let's Practice

Python으로 배우는 소프트웨어 공학 원칙