Учимся писать строки документации в Python🧑🏼💻
Все мы когда-то писали такой код, взглянув на который две недели спустя, трудно было понять почему и как он работает. Нам часто приходится иметь дело с плохо документированным кодом. Но так не должно быть.
Нельзя недооценивать важность написания читаемого кода, который является синонимом качественного документирования кода.
❓Что такое докстринг
Строка документации — это однострочный или многострочный строковый литерал, разделенный тройными одинарными или двойными кавычками """<description>""" в начале модуля, класса, метода или функции, который описывает, что делает функция.
Только в случае, если это первый оператор в функции, он может быть распознан компилятором байт-кода Python и доступен как атрибуты объекта времени выполнения с помощью метода doc или функции help().
def show_docstring():
"""Print function description to user"""
print("Using doc method:")
print(show_docstring.__doc__)
print("Using help() function:")
help(show_docstring)
$ show_docstring();
"Using doc method:"
"Print function description to user"
"Using help() function:"
"Print function description to user"
Лучшие практики:
✅ Все модули, классы, методы и функции, включая конструктор __init__в пакетах, должны иметь строки документации.
✅ Описания пишутся с заглавной буквы и включают пунктуацию в конце предложения.
✅ Всегда окружайте строки документации двойными кавычками по три раза, как показано тут: """Triple double quotes.""".
✅ В конце докстринга пустая строка не ставится.
Однострочные докстринги👇🏻
def power(a, b):
"""Returns arg1 raised to power arg2."""
return a**b
💡 Однострочный докстринг прописывает функцию или действие метода как команду, а не как описание функции: """Do this, return that""".
💡 Однострочный докстринг не является “подписью” function(a, b) -> list , повторяющей параметры функции/метода.
Многострочные докстринги👇🏻
def suggest_places(auth_key, city):
"""Returns longitude and latitude of first suggested location in the Netherlands from Postcode API.
:param auth_key: authorization key for Postcode API
:type auth_key: str
:param city: textual input for city names to match in Postcode API
:type city: str
:rtype: (str, str), str, str
:return: (longitude, latitude), Postcode API status code, Postcode API error message
"""
💡 Многострочные докстринги содержат те же строковые литералы, что и однострочные, но здесь также присутствует описание параметров функции и возвращаемых значений, которое отделено от строки-команды пустой строкой.
Различные конвенции кодирования предписывают стили написания многострочных докстрингов, такие как Google Format и NumPy Format, однако самым простым и традиционным стилем является Sphinx style.
Хотите вторую часть, где мы рассмотрим стиль Sphinx?
✅ Канал с вакансиями:
2 минуты
22 июля 2023