Правила комментирования функций в 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 для поддержания согласованности.

Полезные материалы

1. PEP 257 – "Конвенции докстроков" (Docstring Conventions) — официальные рекомендации по написанию докстроков на Python.
2. Руководство Google по стилю Python — советы от Google по оформлению комментариев и докстроков на Python.
3. Sphinx reStructuredText Primer — отличное введение в синтаксис reStructuredText, широко применяемый в докстроках Python.
4. Наполеон: Движение к более качественным докстрокам — полезные инструменты для написания докстроков в стилях NumPy и Google.
5. "Inspect" — инспекция и анализ кода Python — встроенный в Python инструмент для извлечения информации об объектах во время исполнения.
6. "Functools" — функциональное программирование в Python — использование декоратора functools.wraps для расширения функциональности докстроков.