Docstring

Введение

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

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

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

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

PEP 256 , PEP 257 , PEP 258

Языки, поддерживающие 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: float first addend :param second: float second addend :return: float first + second """ return first + second

Некоторые авторы, в том числе в популярных библиотеках Python вроде datetime , или например, на Pluralsight используют термин Args или Arguments то есть аргументы я считаю это некорректным. Даже в PEP постоянно проскакивают именно аргументы, хотя мы описываем функцию до получения аргументов, то есть говорим про параметры. Если вы можете объяснить почему пишут Arguments - напишите в чат

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

Я бы переписал докстринг так

"""Fetch a list of words from a URL. Returns a list of strings containing the words from the document :param url: string The URL of a UTF-8 text document. :returns: list[str] """

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

doctest

Если в docstring записать вызов фукнции как-будто в интерактивном режиме а затем ожидаемое значение - это можно протестировать с помощью doctest

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

python -m doctest .\docstring.py -v

Как вариант можно было задать такую инструкцию

… if __name__ == '__main__': import doctest doctest.testmod()

Тогда можно запускать следующим способом

python .\docstring.py -v

Trying: sum(0, 1.0) Expecting: 1.0 ok 1 items had no tests: __main__.sum 1 items passed all tests: 1 tests in __main__ 1 tests in 2 items. 1 passed and 0 failed. Test passed.

Изучение 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