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

Введение

Примеры

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

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

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.
"""

Программный доступ к строкам документов

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

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

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

Строка документации можно получить с помощью __doc__ атрибута:

 print(func.__doc__)

Эта функция вообще ничего не делает

 help(func)

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

func()

Эта функция вообще ничего не делает

Еще один пример функции

function.__doc__ только фактическая строка документации в виде строки, в то время как help функция предоставляет общую информацию о функции, включая строку документации. Вот более полезный пример:

 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))

помощь (приветствовать)

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

greet(name, greeting='Hello')

Печать приветствие пользователя name \ Необязательный параметр greeting может изменить то , что они встречали с.

Преимущества строк документации перед обычными комментариями

Просто не вставляя строку документации или обычный комментарий в функцию, это делает ее намного менее полезной.

 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(name, greeting='Hello')

Написать документацию, используя строки документации

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

 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.
    """

Значение строки документации можно получить доступ в программе и - например - используется в help команде.

Синтаксические соглашения ОПТОСОЗ 257

PEP 257 определяет стандарт синтаксиса для комментариев строки документации. Это в основном позволяет два типа:

Однострочные строки документов:

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

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

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

Многострочные строки документов:

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

 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 является инструментом для генерации HTML на основе документации для проектов , основанных на Python строки документации. Его язык разметки используется ReStructuredText.Они определяют свои собственные стандарты в отношении документации, pythonhosted.org Саваофа очень хорошее описание их.Формат сфинкса представляет собой, например , используемую 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 опубликовал Google Python Style Guide , который определяет соглашение кодирования для Python, включая комментарии к документации. По сравнению с Sphinx / reST многие говорят, что документация в соответствии с рекомендациями Google лучше читается человеком.

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

Используя Наполеона плагин, Sphinx может также анализировать документацию в Google Style Guide-совместимый формат.

Функция будет документирована следующим образом в формате руководства по стилю 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