Docstring

Содержание
Введение
Пример написания
help: чтение
Похожие статьи

Введение

В программировании строка документа - это строковый литерал, указанный в исходном коде, который используется, как и комментарий, для документирования определенного сегмента кода.

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

Это позволяет программисту проверять эти комментарии во время выполнения, например, в виде интерактивной справочной системы или в виде метаданных.

По-видимому, он был впервые представлен в оригинальной реализации Emacs TECO.

Языки, поддерживающие docstrings, включают Python (см. PEP 257 ) , Lisp, Elixir, Clojure, Gherkin, Julia и Haskell.

Примеры

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

Например, PyCharm предлагает использовать термин param то есть параметры и я считаю, что это правильно.

def sum(first: float, second: float) -> float: """ Adds two float values :param first: :param second: :return: first + second """ return(first + second)

Некоторые авторы, например, на Pluralsight используют термин Args то есть аргументы я считаю это некорректным.

"""Retrieve and print words from a URL. Usage: python3 words.py <URL> """ import sys from urllib.request import urlopen def fetch_words(url): """Fetch a list of words from a URL. Args: url: The URL of a UTF-8 text document. Returns: A list of strings containing the words from the document """ # PEP 257 # story = urlopen("http://sixty-north.com/c/t.txt") story = urlopen(url) story_words = [] for line in story: line_words = line.decode("utf8").split() for word in line_words: story_words.append(word) story.close() return story_words def print_items(story_words): """Print items one per line. Args: An iterable series of printable items. """ for word in story_words: print(word) def main(url): words = fetch_words(url) print_items(words) if __name__ == "__main__": main(sys.argv[1])

Созданный нами docstring будет хорошо выглядеть в выводе help()

Изучение help

python

Python 3.9.5 (default, Jun 15 2021, 15:30:04) [GCC 9.3.0] on linux Type "help", "copyright", "credits" or "license" for more information.

>>> import words
>>> help(words)

Help on module words: NAME words - Retrieve and print words from a URL. DESCRIPTION Usage: python3 words.py <URL> FUNCTIONS fetch_words(url) Fetch a list of words from a URL. Args: url: The URL of a UTF-8 text document. Returns: A list of strings containing the words from the document main(url) print_items(story_words) Print items one per line. Args: An iterable series of printable items. FILE /home/andrei/python/words.py

Похожие статьи
Основы Python
configparser
docstring
#!: Shebang
Объекты
Итерация
os
pathlib
Изображение баннера

Поиск по сайту

Подпишитесь на Telegram канал @aofeed чтобы следить за выходом новых статей и обновлением старых

Перейти на канал

@aofeed

Задать вопрос в Телеграм-группе

@aofeedchat

Контакты и сотрудничество:
Рекомендую наш хостинг beget.ru
Пишите на info@urn.su если Вы:
1. Хотите написать статью для нашего сайта или перевести статью на свой родной язык.
2. Хотите разместить на сайте рекламу, подходящую по тематике.
3. Реклама на моём сайте имеет максимальный уровень цензуры. Если Вы увидели рекламный блок недопустимый для просмотра детьми школьного возраста, вызывающий шок или вводящий в заблуждение - пожалуйста свяжитесь с нами по электронной почте
4. Нашли на сайте ошибку, неточности, баг и т.д. ... .......
5. Статьи можно расшарить в соцсетях, нажав на иконку сети: