Я работал над учебником по Real Python и узнал интересный факт, который восполнил пробел, который я заметил ранее.
Несколько лет назад я написал небольшое приложение на Python для обработки данных от источника к месту назначения SQL Server. Я изучал Python небольшими порциями с 2017 года; хотя у меня было достаточно знаний для создания рабочего решения, было много вещей, которые, как я знаю, я хотел бы рефакторить или сделать более эффективным. Одним из таких пунктов было желание предоставить описание для функций, которые я абстрагировал для приложения.
В учебнике по Real Python учитель рассказывал о docstrings, строковом литерале. Когда он встречается в качестве первого оператора в функции, он выступает в качестве специального атрибута и отображает объяснение функции. Лучшая практика заключается в том, что это не должно быть повторением сигнатуры функции, поскольку она уже будет отображена, а кратким объяснением назначения функции.
Вот пример функции без doc-строки — отображается только сигнатура функции, если она предоставлена:
def function1():
return "Hi there"
Вот пример функции с документальной строкой — в контекстной справке отображается текст из документальной строки, а также сигнатура функции, если таковая имеется:
def function2():
"""Returns a greeting in Portuguese with no variable"""
return "Ola, prazer em conhecer"
Это позволяет прояснить загадки в вашем коде, независимо от того, находятся ли все ваши функции в одном файле или нет. Вы можете быстро вспомнить, почему вы абстрагировались от кода и как вы собирались его использовать. Эту функциональность можно и нужно использовать для методов, которые являются членами класса, чтобы разработчики, использующие ваш код, понимали назначение метода. Все те же самые лучшие практики будут применимы.
Когда у меня появится возможность рефакторинга моего приложения Python для обработки данных, я воспользуюсь докстрингами, чтобы помочь себе и другим разработчикам быстро понять, что делает каждая функция.