Введение
Примеры
Однострочные, встроенные и многострочные комментарии
Комментарии используются для объяснения кода, когда сам основной код неясен.
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
