Правила комментирования функций в Python: лучшие практики
Быстрый ответ
Стандартом для документации функций в Python являются докстроки. Написание докстроков считается правилом хорошего тона в программировании на Python. Докстроки помещаются непосредственно под строкой, в которой объявляется функция, и обрамляются парой трех двойных кавычек ("""
). В докстроках кратко описываются цель функции, принимаемые ею аргументы и возвращаемое значение.
def multiply(a, b):
"""Умножает 'a' на 'b' и возвращает результат."""
return a * b
Докстроки – это не просто пояснение к вашему коду на письменном языке, но и способ автоматизировать процесс создания документации. Они соответствуют стандартам PEP 257, который устанавливает рекомендации по оформлению докстроков в Python.
Разбираемся с наилучшими практиками написания докстроков
Делайте докстроки понятными и запоминающимися.
Не лимитируйте себя простым перечислением деталей. Ваши докстроки должны служить обстоятельными руководствами, информируя о типе и смысле параметров, возможных результатах выполнения, побочных эффектах и об исключительных ситуациях, с которыми код может столкнуться. Главное – ваш код должен давать прогнозируемые результаты, а не неожиданные сюрпризы.
Приводите примеры использования при помощи доктестов
Выходите за рамки простых описаний, продемонстрируйте применение функции на практике, используя доктесты в докстроках. Доктесты Сразу решают две задачи: они обучают и служат в качестве простого инструмента для юнит-тестирования.
def add(a, b):
"""
Складывает 'a' и 'b', возвращая результат.
Обратите внимание: функция работает с числовыми аргументами.
:param a: первое слагаемое.
:param b: второе слагаемое.
:return: сумма 'a' и 'b'.
>>> add(2, 3)
5
"""
return a + b
Используйте Sphinx для создания документации
Если ваш код снабжен ясными и хорошо оформленными докстроками, можно использовать инструменты, вроде Sphinx, чтобы сгенерировать из них структурированную и эстетически приятную документацию.
Адаптируйте длину докстрок под размер функций
Степень детализации докстрока должна зависеть от сложности функции: для объемных функций подойдут многострочные докстроки, в то время как для простых и интуитивно понятных функций достаточно однострочных.
def is_even(number):
"""Проверяет, является ли число четным."""
return number % 2 == 0
Визуализация
Можно сравнить сочинение докстроков с прописыванием рецепта:
- **Название блюда**: суть вашего рецепта. 🍲
- **Ингредиенты**: необходимые ингредиенты. 🌿
- **Приготовление**: процесс приготовления блюда. 🔪
- **Подача на стол**: финальный результат. 🍽️
Подобное структурированное представление могут иметь и ваши функции в Python:
"""
Фрагмент докстроки:
Функция: fry_egg 🍳
Ингредиенты: яйцо (входной аргумент 1), масло (входной аргумент 2)
Принцип приготовления: смазать маслом сковороду и поджарить на ней яйцо.
Результат: отлично приготовленный завтрак.
"""
📗🥄 Ваша документация, как и любой рецепт, должна быть точной и оставлять минимум места для толкования!
Максимизация использования докстроков
Пользуйтесь интерактивной помощью
Качественно написанная докстрока позволит эффективно использовать встроенную функцию help()
Python и избавить вас от лишних вопросов по работе этой функции.
help(multiply)
Уделяйте внимание чистоте кода
Загромождение функции вспомогательными комментариями (типа хэш pylint в духе # pylint: disable=
) недопустимо. Стремитесь к чистоте кода!
Будьте ясными
Ваша функция должна быть весьма собой законченной и понятной. Явно указывайте требуемый контекст и предварительные условия работы функции.
Простота – ключ к успеху
ASCII-арт может использоваться в качестве оформления, но докстроки должны быть лаконичными, чистыми и легкими для чтения.
Философия написания докстроков
Общайтесь на языке пользователя
Будьте проводником по своему коду, акцентируйте внимание на общем поведении функции, а детали реализации оставляйте в коде.
Обращайте внимание на предположения
Если функция требует определенного начального состояния системы или зависит от внесенных в нее изменений, упомяните об этом.
Следуйте стандартам
Единый стиль документации крайне важен, особенно в крупных проектах. Отталкивайтесь от PEP 258, Sphinx и соглашений PyCharm для поддержания согласованности.
Полезные материалы
- PEP 257 – "Конвенции докстроков" (Docstring Conventions) — официальные рекомендации по написанию докстроков на Python.
- Руководство Google по стилю Python — советы от Google по оформлению комментариев и докстроков на Python.
- Sphinx reStructuredText Primer — отличное введение в синтаксис reStructuredText, широко применяемый в докстроках Python.
- Наполеон: Движение к более качественным докстрокам — полезные инструменты для написания докстроков в стилях NumPy и Google.
- "Inspect" — инспекция и анализ кода Python — встроенный в Python инструмент для извлечения информации об объектах во время исполнения.
- "Functools" — функциональное программирование в Python — использование декоратора
functools.wraps
для расширения функциональности докстроков.