А DOCSTRING Описывает модуль, функцию, класс или метод на простом английском языке, чтобы помочь другим кодерам понять смысл лучше. Вы должны определить DOCSTRING в начале модуля, функции, класса или определения метода. Делая это, DocString становится __doc__ Специальный атрибут этого объекта. Вы можете получить доступ к Docstring любого объекта Python, вызывая его __doc__ атрибут.
Вы можете найти полный учебник на DocString в моем блоге статьи: что такое __ doc __ в Python?
Давайте кратко посмотрим на минимальный пример DOCSTRING:
s = 'hello world' print(s.__doc__)
Выходная мощность представляет собой следующую многострочную Docsstring объекта функции строки:
''' str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'. '''
Но как вы можете определить DOCSTRING в одной строке Python Code?
DOCSTRING может быть определен в нескольких строках, используя тройные цитаты или в одной строке.
Однострочная DOCSTRING
За Конвенция , Вы используете однострочные DocStrings, если функция, модуль, класс или метод достаточно очевидны, чтобы гарантировать краткое объяснение, но ничего не значит. Вы можете заключить одноклассник DOCSTRING в рамках одиночных кавычек, двойных кавычек или даже тройных цитатов. Однако включение одноклассника DOCSTRING в тройной цитате является самым питонным способом.
Например, следующая функция может быть легко понята. Следовательно, одноклассник DOCSTRING достаточно для описания его поведения:
def add(x, y):
'''Add both arguments and returns their sum.'''
return x + y
print(add.__doc__)
# Add both arguments and returns their sum.Есть несколько конвенций, которые следует учитывать при написании одноклассников Docstrings:
- Используйте тройные цитаты для одноклассника DOCSTRING – даже если это не требуется строго. Он улучшает согласованность и упрощает более поздние расширения DOCSTRING.
- Поместите закрывающие цитаты на той же линии, что и открывающие цитаты для ясности. В противном случае это не было бы одноклассника DOCSTRING в первую очередь.
- Не используйте пустую строку до или после DocString. Просто начните кодировать прямо сейчас!
- Если возможно, сформулируйте DOCSTRING в виде фразы в течение периода. Почему? Поскольку это побуждает вас писать предписывающие документы, такие как «do x» или “возврат y”, а не описательные “возвращает x” или “делает Y”.
- Не используйте DOCSTRING как «подпись», повторяя информацию, уже приведенную в определении функции/метода.
Все идет нормально. Но если это одноклассник DOCSTRING – как выглядит многострочная DocString?
Многострочная DOCSTRING
Многострочная DOCSTRING состоит из нескольких строк кода Python:
def add(a=0, b=2):
"""Add two integers.
Keyword arguments:
a -- the first argument (default 0)
b -- the second argument (default 2)
"""
if a == 0:
return b
else:
return a + bВ этом случае многострочная DocString более сложна. Сначала он начинается с общего описания функции, а затем списку подобное объяснением всех аргументов. Это чистый и читаемый способ написать Docstrings!
Попробуйте сами: посмотрите на следующий интерактивный код Shell:
Упражнение : Распечатайте DOCSTRING на оболочку Python и запустите его в браузере!
Лучшие практики
Есть пара лучших практик, называемых Конвенции DOCSTRING Как определено в Официальный PEP Standard Отказ Придерживаться их при определении ваших документов. Вот 7 самых важных конвенций DocString:
- Все модули, функция, методы и классы должны иметь DocStrings.
- Всегда используйте
"" "Тройные двойные цитаты" ""вокруг ваших докладов по соображениям согласованности. - Используйте тройные цитаты, даже если DocString вписывается в одну строку. Это позволяет легко расширить.
- Нет пустой строки до или после DocString – за исключением классов, где вы должны добавить одну строку после DocString.
- Используйте фразу, которая описывает, что ваш код делает такой как
"" "ДО X и верните Y." ""окончание в течение периода. Не используйте описание, такое как"" "Есть ли х и возвращает Y." ""Отказ - Multi-line Docstrings Начните с сводной строки (например, одноклассник DOCSTRING), за которым следует пустая строка, а затем более близкое описание, такое как
Аргумент - имя человека (строка)описать один из аргументов функции или метода. Например, вы можете использовать одну строку на аргумент. - Начните многострочную DocString сразу в той же линии открытия
«« Тройные двойные струны ...вместо начала текста в новой строке.
Куда пойти отсюда?
Достаточно теории, давайте познакомимся!
Чтобы стать успешным в кодировке, вам нужно выйти туда и решать реальные проблемы для реальных людей. Вот как вы можете легко стать шестифункциональным тренером. И вот как вы польские навыки, которые вам действительно нужны на практике. В конце концов, что такое использование теории обучения, что никто никогда не нуждается?
Практические проекты – это то, как вы обостряете вашу пилу в кодировке!
Вы хотите стать мастером кода, сосредоточившись на практических кодовых проектах, которые фактически зарабатывают вам деньги и решают проблемы для людей?
Затем станьте питоном независимым разработчиком! Это лучший способ приближения к задаче улучшения ваших навыков Python – даже если вы являетесь полным новичком.
Присоединяйтесь к моему бесплатным вебинаре «Как создать свой навык высокого дохода Python» и посмотреть, как я вырос на моем кодированном бизнесе в Интернете и как вы можете, слишком от комфорта вашего собственного дома.
Присоединяйтесь к свободному вебинару сейчас!
Работая в качестве исследователя в распределенных системах, доктор Кристиан Майер нашел свою любовь к учению студентов компьютерных наук.
Чтобы помочь студентам достичь более высоких уровней успеха Python, он основал сайт программирования образования Finxter.com Отказ Он автор популярной книги программирования Python One-listers (Nostarch 2020), Coauthor of Кофе-брейк Python Серия самооставленных книг, энтузиаста компьютерных наук, Фрилансера и владелец одного из лучших 10 крупнейших Питон блоги по всему миру.
Его страсти пишут, чтение и кодирование. Но его величайшая страсть состоит в том, чтобы служить стремлению кодер через Finxter и помогать им повысить свои навыки. Вы можете присоединиться к его бесплатной академии электронной почты здесь.