Несмотря на то, что строки документации предлагают разработчикам ключевой способ улучшить читаемость кода, их часто упускают из виду как при обучении, так и на практике.
Введение
Согласно 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 рисует гораздо более четкую картину того, что делает функция, верно? Итак, я не написал функцию, описанную в строке документации, однако вы, вероятно, имеете какое-то представление о том, что это будет!
Заключение
В этом сообщении блога мы рассмотрели, что такое строки документации, почему они важны и какие преимущества они приносят для включения их в ваше кодирование в будущем. Надеюсь, вы нашли это полезным и учтете поднятые здесь вопросы, когда будете продвигать проекты в будущем!
Всего наилучшего
~ Итан