Python Language
Комментарии и документация

Синтаксис

• # Это однострочный комментарий
• print ("") # Это встроенный комментарий
• «»»
  Это
  многострочный комментарий
  «»»

замечания

Однострочные, встроенные и многострочные комментарии

Комментарии используются для объяснения кода, когда сам базовый код не ясен.

Python игнорирует комментарии и поэтому не выполняет код там, или повышает синтаксические ошибки для простых английских предложений.

Однострочные комментарии начинаются с символа хеша ( # ) и заканчиваются концом строки.

• Комментарий одиночной строки:

# 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

Docstrings - в отличие от обычных комментариев - сохраняются как атрибут функции, которую они документируют, что означает, что вы можете получить к ним доступ программно.

Примерная функция

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

Доступ к docstring можно получить с __doc__ атрибута __doc__ :

print(func.__doc__)

Это функция, которая ничего не делает

help(func)

Справка по функции func в модуле __main__ :

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)

Справка по функции greet в модуле __main__ :

greet(name, greeting='Hello')

Печать приветствие пользователя name
Дополнительное 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')

Напишите документацию с помощью docstrings

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. Он в основном позволяет использовать два типа:

• Однострочные Docstrings:

Согласно PEP 257, они должны использоваться с короткими и простыми функциями. Все помещается в одну строку, например:

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

Докштрина заканчивается периодом, глагол должен быть в императивной форме.

• Многострочные Docstrings:

Многострочная docstring должна использоваться для более длинных, более сложных функций, модулей или классов.

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)

Они начинаются с краткой сводки (эквивалентной содержимому однострочной docstring), которая может быть в той же строке, что и кавычки или на следующей строке, дает дополнительные детали, параметры списка и возвращаемые значения.

Примечание. PEP 257 определяет, какая информация должна быть указана в docstring, она не определяет, в каком формате она должна быть указана. Именно по этой причине другие стороны и инструменты синтаксического анализа документации указали свои собственные стандарты для документации, некоторые из которых перечислены ниже и в этом вопросе .

сфинкс

Sphinx - это инструмент для создания документации на основе HTML для проектов Python на основе docstrings. Используемый язык разметки - reStructuredText . Они определяют свои собственные стандарты для документации, у pythonhosted.org есть очень хорошее описание . Формат Sphinx, например, используется IDE pyCharm .

Функция будет задокументирована так, используя формат 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 опубликовал руководство по стилю Google Python, которое определяет соглашения о кодировании для Python, включая комментарии к документации. По сравнению с Sphinx / reST многие говорят, что документация в соответствии с рекомендациями Google лучше читается человеком.

На упомянутой выше странице pythonhosted.org также приводятся некоторые примеры хорошей документации в соответствии с Руководством по стилю Google.

Используя плагин Napoleon , Sphinx также может анализировать документацию в формате, соответствующем Руководству по стилю 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