Несмотря на то, что строки документации предлагают разработчикам ключевой способ улучшить читаемость кода, их часто упускают из виду как при обучении, так и на практике.

Введение

Согласно PEP 257, строка документации — это строковый литерал, который встречается в качестве первого оператора в определении модуля, функции, класса или метода. Такая строка документации становится специальным атрибутом __doc__ этого объекта. Он используется для описания функциональности модуля или функции, включая параметры и возврат, если они присутствуют.

В моих многочисленных встречах с учебными материалами по Python я никогда не сталкивался с каким-либо содержанием, объясняющим, что такое строки документации и преимущества их использования. В оставшейся части этого поста мы рассмотрим лучшие практики, некоторые примеры, а также преимущества четкой, хорошо написанной строки документации.

Лучшие практики и преимущества

Строка документации обычно определяется в определении функции или класса с использованием тройных двойных кавычек и разбивается на 3 четко определенных раздела:

  • Описание функционала.
  • Разбивка любых параметров, если они есть.
  • Разбивка возврата, если таковая имеется.

Целью любой строки документации является объяснение той части кода, на которую она ссылается, чтобы любой новый пользователь, просматривающий ее, мог понять, в общем смысле, что делает этот раздел.

Из этого мы можем почти вывести преимущества наличия строк документации в ваших проектах:

  • Повышенная читабельность, особенно для тех, кто никогда раньше не просматривал код.
  • Простота тестирования, четкие описания функций облегчают написание полных юнит-тестов.
  • Помогает писать четкий и целостный код — часто легко увлечься, поэтому просмотр ключей строк документации работает по делу.

Пример

В этом примере давайте рассмотрим 2 разные версии строки документации функции Python…

Версия А

def filter_systems(data, threshold, keep_duplicate=False)
"""
A filter for systems that don't match the threshold.
"""

по сравнению с версией B

def filter_systems(data, threshold, keep_duplicate=False)
"""
A simple filter that removes systems that are beneath the user-defined x-value threshold.
Parameters
----------
`data` : Pandas DataFrame
    A pandas dataframe containing the systems from the xyz dataset. Must include columns 'x' and 'y'. All timestamp columns must be timezone aware.
`threshold` : float
    A float threshold for the x-value to be applied to the filter. Must be between 1 and 10.
`keep_duplicates` : Boolean
    Defaults to False. A boolean value determining whether duplicate systems should be removed in the filter.
Returns
-------
`filtered_data` : Pandas DataFrame
A pandas dataframe containing the filtered systems from the xyz dataset. Must include columns 'x' and 'y'. All timestamp columns must be timezone aware.
"""

Теперь из двух вышеупомянутых версий версия B рисует гораздо более четкую картину того, что делает функция, верно? Итак, я не написал функцию, описанную в строке документации, однако вы, вероятно, имеете какое-то представление о том, что это будет!

Заключение

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

Всего наилучшего

~ Итан