Учимся писать строки документации в 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? ✅ Канал с вакансиями: https://t.me/GO_TO_IT_jobs
1 год назад