Docstring

Введение

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

В отличие от обычных комментариев к исходному коду или даже специально отформатированных комментариев, таких как 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