Skip to content

Latest commit

 

History

History
161 lines (127 loc) · 6.27 KB

BetterWay84.md

File metadata and controls

161 lines (127 loc) · 6.27 KB
Raw

84. 모든 함수, 클래스, 모듈에 독스트링을 작성하라

1. 문서화

  • 파이선은 언어 자체의 동적 특성으로 인해 문서화 중요

    • 코드 블록에 문서를 첨부하는 기능 제공
    • 다른 언어와 달리 프로그램 실행 중에 프로그램 소스 코드 문서에 직접 접근 가능
    • 아래 예제에서 독 스트링을 가져오려면 __doc__ 특별 애트리뷰트 사용
    def palindrome(word):
    """주어진 단어가 회문인 경우 True를 반환한다."""
    return word == word[::-1]

assert palindrome('tacocat')
assert not palindrome('banana')
    print(repr(palindrome.__doc__))

>>>
'주어진 단어가 회문인 경우 True를 반환한다.'

  • 내장 pydoc 모듈을 사용해 로컬 웹 서버 실행 가능

  • 사용자가 작성한 모듈 뿐만 아니라 인터프리터에서 찾을 수 있는 모든 파이선 문서 제공

$ python3 -m pydoc -p 1234
Server ready at http://localhost:1234/
Server commands: [b]rowser, [q]uit
server> b
  • 독 스트링을 함수, 클래스, 모듈에 첨부 가능
  • 파이선 독스트링과 __doc__ 애트리뷰트 지원으로 3가지 효과를 얻을 수 있음
    1. 문서에 항상 접근 가능하므로 대화식 개발이 쉬워짐
    2. 코드 문서화를 정의하는 표준이 있으므로 문서 본문을 더 보기 좋은 형태로 바꿔주는 도구를 쉽게 만들 수 있음
    3. 파이선이 제공하는 훌륭하고 접근하기 쉽고 보기 좋은 문서들로 인해 사용자들이 더 많은 문서를 작성하게 됨

2. 모듈 문서화하기

  • 각 모듈에는 최상위 독스트링이 있어야 함
  • 세 개의 큰 따옴표로 시작
  • 첫 줄
    • 목적을 설명하는 한 문장
  • 다음 단락
    • 사용자들이 모듈의 동작에 대해 알아둬야 하는 세부 사항을 적어야 함
# words.py
#!/usr/bin/env python#3
"""단어의 언어 패턴을 찾을 때 쓸 수 있는 라이브러리.

여러 단어가 서로 어떤 연관 관계에 있는지 검사하는 것이 어려울 때가 있다!
이 모듈은 단어가 가지는 특별한 특성을 쉽게 결정할 수 있게 해준다.

사용 가능 함수:
- palindrome: 주어진 단어가 회문인지 결정한다.
- check_anagram: 주어진 단어가 어구전철(똑같은 글자들로 순서만 바뀐 경우)인지 결정한다.
...
"""
...

3. 클래스 문서화하기

  • 각 클래스는 클래스 수준의 독스트링을 포함해야 함
  • 모듈 수준 독스트링과 거의 비슷한 패턴을 따름
  • 첫 줄
    • 클래스 목적을 알려주는 한 문장
  • 다음 단락
    • 클래스의 동작 세부 사항 및 중요 부분
  • 중요 공개 애트리뷰트, 메소드 강조 표시
  • 상속 관계나 protected 애트리뷰트나 메소드와 상호작용 방법 안내 필요
class Player:
    """게임 플레이어를 표현한다.

    하위 클래스는 `tick` 메서드를 오버라이드해서 플레이어의 파워 레벨 등에 맞는
    움직임 애니메이션을 제공할 수 있다.
    
    공개 애트리뷰트:
    - power: 사용하지 않은 파워업들(0과 1 사이의 float).
    - coins: 현재 레벨에서 발견한 코인 개수(integer).
    """
    ...

4. 함수 문서화하기

  • 모든 공개 함수와 메소드에는 독스트링을 포함시켜야 함
  • 모듈, 클래스 독스트링과 같은 패턴을 따름
  • 첫 줄
    • 함수 목적 설명
  • 다음 단락
    • 함수 인자, 함수 동작에 대해 구체적 설명
    • 반환값 설명
    • 호출부 처리 예외 설명
  • 함수 독스트링 작성 규칙
    1. 함수에 인자가 없고 반환값만 있다면 설명은 한 줄로 가능
    2. 함수가 아무 값도 반환하지 않는다면 return None 대신 반환값에 대한 설명을 제외하는 것이 나음
    3. 함수 인터페이스에 예외 발생이 포함된다면 발생하는 예외와 예외가 발생하는 상황 설명을 포함해야 함
    4. 일반적인 동작 중 함수가 예외를 발생시키지 않을 것으로 예상한다면 예외 발생않는 사실 적지 말라
    5. 함수가 가변 인자나 키워드 인자를 받는다면, 문서화한 인자 목록에 *arg, **kwargs 사용, 각각의 목적 설명 필요
    6. 함수가 제너레이터라면 이 제너레이터를 이터레이션할 때 어떤 값이 발생하는 기술 필요
    7. 함수가 비동기 코루틴이라면 언제 이 코루틴의 비동기 실행이 중단되는 설명 필요
def find_anagrams(word, dictionary):
    """주어진 단어의 모든 어구전철을 찾는다.

    이 함수는 '딕셔너리' 컨테이너의 원소 검사만큼 빠른 속도로 실행된다.

    Args:
        word: 대상 단어. 문자열.
        dictionary: 모든 단어가 들어 있는 collections.abc.Container 컬렉션.

    Returns:
        찾은 어구전철들로 이뤄진 리스트. 아무것도 찾지 못한 경우 Empty.
    """
    ...

5. 독스트링과 타입 애너테이션 사용하기

  • 타입 애너테이션이 제공하는 정보는 전형적인 독스트링이 제공하는 정보와 중복될 수 있음
  • 타입 애너테이션을 붙인 find_anagrams 함수 시그니처 예제
from typing import Container, List

def find_anagrams(word: str,
                  dictionary: Container[str]) -> List[str]:
    ...
  • 독스트링에서 word 가 문자열이라고 설명할 필요 없음
  • dictionary 인자가 collections.abc.Container 라는 설명도 필요 없음
  • 타입 애너테이션으로 많은 부분을 설명할 수 있으므로 아래 예제에서와 같이 중복된 부분은 명시를 피해야 함
def find_anagrams(word: str,
                  dictionary: Container[str]) -> List[str]:
    """주어진 단어의 모든 어구전철을 찾는다.

    이 함수는 '딕셔너리' 컨테이너의 원소 검사만큼 빠른 속도로 실행된다.

    Args:
        word: 대상 단어. 
        dictionary: 모든 단어가 들어 있는 컬렉션.

    Returns:
        찾은 어구전철들.
    """
    ...