Кодовая документация является неотъемлемой частью опыта разработки Python. Иногда в источнике может быть больше документации, чем сам код. Это помогает вам понять, что делает функция или класс, какие аргументы он принимает, и что она возвращает.
Python предоставляет удобный способ добавления документации. Строка документации или Docstring – это строковая буквальная, и она используется в классах, модулях, функциях или определениях методов. Docstring очень похож на комментарий, но представлен с тройной дубльской цитатой (“” “”).
Docstrings доступны по __doc__ Атрибут объектов, а также со встроенным help () функция
Пример Docstring:
В этом примере мы определили функцию CAT, которая возвращает Meow. Мы объявили Docstring, который объясняет, что делает функция. Чтобы получить документ функции, нам нужно отобразить атрибут DOC ( print (cat .__ Doc__) )
Есть несколько способов написать Docstring, то есть однострочный Docstring и многострочный Docstring.
Однострочные докажины
В зависимости от сложности функции, метода или класса, однострочный DocString может быть совершенно уместным.
Например:
Заключительные кавычки находятся на той же строке, что и вступительные цитаты. Вы можете использовать одну из цитат, то есть тройные сингл или тройные цитаты. Там нет пустой линии ни до, ни после Docstring.
Многострочные документы
В более сложных случаях лучше дать дополнительную информацию о коде. Multi-Line Docstrings состоят из сводной строки, такой как однострочный Docstring, за которым следует одна пустая строка с описательным текстом.
Общий формат для написания многострочного Docstring:
Как вы можете видеть, Docstring улучшает удобство использования и читаемость кода. Программисту будет легко, который не написал код, чтобы понять, что делает эта или иная функция. Самое важное, что нужно помнить при работе с DocStrings, это то, что вы пишете Docstring для людей, которые будут использовать ваш код.
Тем не менее, Docstrings – очень обширная тема, и если вы хотите узнать больше, ознакомьтесь с Python Docstrings PEP257 Анкет
Оригинал: “https://dev.to/highflyer910/what-is-a-python-docstring-44eo”