Python Language
의견 및 문서

통사론

• # 이것은 한 줄 주석입니다.
• print ( "") # 이것은 인라인 주석입니다.
• "" "
  이것은
  여러 줄 주석
  "" "

비고

한 줄, 인라인 및 여러 줄 주석

주석은 기본 코드 자체가 명확하지 않을 때 코드를 설명하는 데 사용됩니다.

파이썬은 주석을 무시하므로 코드가 실행되지 않으며 일반 영어 문장의 구문 오류가 발생합니다.

한 줄 주석은 해시 문자 ( # )로 시작하고 줄 끝으로 끝납니다.

• 한 줄 주석 :

# This is a single line comment in Python

• 인라인 코멘트 :

print("Hello World")  # This line prints "Hello World"

• 여러 줄에 걸쳐있는 주석은 양쪽 끝에 """ 또는 ''' 이 있습니다. 이것은 여러 줄 문자열과 동일하지만 주석으로 사용할 수 있습니다.

"""
This type of comment spans multiple lines.
These are mostly used for documentation of functions, classes and modules.
"""

프로그래밍 방식으로 docstrings에 액세스

Docstring은 일반 주석과 달리 문서화 된 함수의 속성으로 저장되므로 프로그래밍 방식으로 액세스 할 수 있습니다.

예제 함수

def func():
    """This is a function that does nothing at all"""
    return

docstring은 __doc__ 속성을 사용하여 액세스 할 수 있습니다.

print(func.__doc__)

이것은 아무것도하지 않는 함수입니다.

help(func)

__main__ 모듈의 function func 에 대한 도움말 :

func()

이것은 아무것도하지 않는 함수입니다.

또 다른 예제 함수

function.__doc__ 은 실제의 docstring을 문자열로, help 함수는 docstring을 포함하여 함수에 대한 일반적인 정보를 제공합니다. 다음은 유용한 예입니다.

def greet(name, greeting="Hello"):
    """Print a greeting to the user `name`

    Optional parameter `greeting` can change what they're greeted with."""
    
    print("{} {}".format(greeting, name))

help(greet)

함수에 대한 도움말은 모듈 __main__ 에서 greet 합니다 :

greet(name, greeting='Hello')

사용자 name 인사말을 인쇄하십시오.
선택적 매개 변수 greeting 하면 greeting 을 변경할 수 있습니다.

정기적 인 주석보다 docstrings의 장점

함수에 docstring이나 일반 주석을 두지 않으면 도움이되지 않습니다.

def greet(name, greeting="Hello"):
    # Print a greeting to the user `name`
    # Optional parameter `greeting` can change what they're greeted with.
    
    print("{} {}".format(greeting, name))

print(greet.__doc__)

없음

help(greet)

기능에 대한 도움말은 모듈 main 에서 인사합니다 :

greet(name, greeting='Hello')

docstring을 사용하여 문서 작성

docstring 은 모듈, 클래스, 함수 및 메소드를 문서화하는 데 사용되는 여러 줄 주석 입니다. 설명하는 구성 요소의 첫 번째 문장이어야합니다.

def hello(name):
    """Greet someone.

    Print a greeting ("Hello") for the person with the given name.
    """

    print("Hello "+name)

class Greeter:
    """An object used to greet people.

    It contains multiple greeting functions for several languages
    and times of the  day.
    """

docstring의 값은 프로그램 내에서 액세스 할 수 있으며 예를 들어 help 명령에서 사용합니다.

구문 규칙

PEP 257

PEP 257 은 docstring 주석에 대한 구문 표준을 정의합니다. 기본적으로 두 가지 유형이 있습니다.

• 한 줄의 문서 문자열 :

PEP 257에 따르면, 그들은 짧고 간단한 기능으로 사용되어야합니다. 모든 것이 한 줄에 표시됩니다 (예 :

def hello():
    """Say hello to your friends."""
    print("Hello my friends!")

문서화 문자열은 마침표로 끝나야하며, 동사는 필수 형식이어야합니다.

• 멀티 라인 Docstrings :

더 길고 복잡한 함수, 모듈 또는 클래스에는 다중 행 문서 문자열을 사용해야합니다.

def hello(name, language="en"):
    """Say hello to a person.

    Arguments:
    name: the name of the person
    language: the language in which the person should be greeted
    """

    print(greeting[language]+" "+name)

그들은 따옴표와 같은 줄에 있거나 다음 줄에있을 수있는 짧은 요약 (한 줄 문서 문자열의 내용에 해당)으로 시작하여 추가 세부 정보 및 목록 매개 변수와 반환 값을 제공합니다.

주 PEP 257은 문서화 문자열 내에 어떤 정보가 주어져야 하는지를 정의하고, 어떤 형식으로 정보를 제공해야 하는지를 정의하지 않는다. 이것은 타 당사자 및 문서 파싱 도구가 문서에 대한 자체 표준을 지정하는 이유였으며 그 중 일부는 아래 및 이 질문 에 나열되어 있습니다.

스핑크스

Sphinx 는 문서화 문자열을 기반으로하는 Python 프로젝트 용 HTML 기반 문서를 생성하는 도구입니다. 사용 된 마크 업 언어는 reStructuredText 입니다. 그들은 문서화를위한 그들 자신의 표준을 정의 합니다 . pythonhosted.org 는 그것들에 대한 아주 좋은 설명을 제공합니다 . Sphinx 형식은 예를 들어 pyCharm IDE에서 사용됩니다.

함수는 다음과 같이 Sphinx / reStructuredText 형식을 사용하여 문서화됩니다.

def hello(name, language="en"):
    """Say hello to a person.

    :param name: the name of the person
    :type name: str
    :param language: the language in which the person should be greeted
    :type language: str
    :return: a number
    :rtype: int
    """

    print(greeting[language]+" "+name)
    return 4

Google Python 스타일 가이드

Google은 문서 주석을 포함하여 Python의 코딩 규칙을 정의한 Google Python 스타일 가이드 를 발행했습니다. Sphinx / reST와 비교하여 많은 사람들은 Google의 가이드 라인에 따른 문서가 사람이 읽을 수있는 편이 낫다고 말합니다.

위에 언급 된 pythonhosted.org 페이지 는 Google 스타일 가이드에 따라 좋은 문서를위한 몇 가지 예를 제공합니다.

Sphinx는 Napoleon 플러그인을 사용하여 Google 스타일 가이드 규격 형식의 문서를 구문 분석 할 수 있습니다.

함수는 다음과 같이 Google 스타일 가이드 형식을 사용하여 문서화됩니다.

def hello(name, language="en"):
    """Say hello to a person.

    Args:
        name: the name of the person as string
        language: the language code string

    Returns:
        A number.
    """

    print(greeting[language]+" "+name)
    return 4