Python - Docstrings

Привет, стремящиеся к знаниям программисты Python! Сегодня мы погрузимся в увлекательный мир docstrings. Как ваш добрый сосед-преподаватель информатики, я рад вести вас через этот важный аспект программирования на Python. Так что взяйте свой любимый напиток, устроитесь комфортно и давайте начнем это увлекательное путешествие в мир знаний вместе!

Docstrings в Python

Представьте себе, что вы пишете дневник. В начале каждой записи вы можете набросать краткое резюме того, что произошло в тот день. Docstrings в Python несколько похожи на это! Это особые строки, которые описывают, что делает кусок кода, делая его легче для вас (и других) понять ваш код позже.

В Python docstrings заключены в тройные кавычки (""" или ''') и помещены сразу после определения функции, класса или модуля. Давайте рассмотрим простой пример:

def приветствие(имя):
"""Эта функция приветствует человека, переданного в качестве параметра"""
print(f"Привет, {имя}!")

В этом примере строка между тройными кавычками — это наш docstring. Он кратко объясняет, что делает функция приветствие.

Однострочные Docstrings

Для простых функций или классов однострочный docstring может быть вам достаточно. Вот еще один пример:

def квадрат(n):
"""Возвращает квадрат числа."""
return n ** 2

Этот docstring короткий и доходчивый, намертво говоря нам, что делает функция, всего в одной строке.

Многострочные Docstrings

Для более сложных функций или классов вам может понадобиться многострочный docstring. Они обычно включают строку резюме, за которой следует пустая строка, а затем более подробная информация. Давайте посмотрим на пример:

def вычислить_площадь(длина, ширина):
"""
Вычисляет площадь прямоугольника.

Параметры:
длина (float): Длина прямоугольника
ширина (float): Ширина прямоугольника

Возвращает:
float: Площадь прямоугольника
"""
return длина * ширина

Этот многострочный docstring предоставляет более подробную информацию о параметрах функции и о том, что она возвращает.

Docstrings для модулей

Модули также могут иметь docstrings! Они помещаются в начале файла. Например:

"""
Этот модуль содержит утилитарные функции для геометрических вычислений.
Он включает функции для вычисления площадей и объемов различных фигур.
"""

def вычислить_площадь_круга(радиус):
# Реализация функции здесь

Docstrings для классов

Классы также могут иметь docstrings. Они помещаются сразу после определения класса:

class Прямоугольник:
"""
Класс, представляющий прямоугольник.

Атрибуты:
длина (float): Длина прямоугольника
ширина (float): Ширина прямоугольника
"""

def __init__(self, длина, ширина):
self.длина = длина
self.ширина = ширина

Доступ к Docstrings

Одна из интересных вещей о docstrings заключается в том, что вы можете получить к ним программно. Python сохраняет docstring как атрибут __doc__ функции, класса или модуля. Вот как к нему можно получить доступ:

def приветствие(имя):
"""Эта функция приветствует человека, переданного в качестве параметра"""
print(f"Привет, {имя}!")

print(приветствие.__doc__)

Это выведет: Эта функция приветствует человека, переданного в качестве параметра

Лучшие практики для написания Docstrings

Теперь, когда мы знаем, как писать docstrings, давайте поговорим о некоторых лучших практиках:

1. Будьте лаконичными, но информативными
2. Используйте правильную грамматику и пунктуацию
3. Будьте последовательны в своем стиле
4. Включайте информацию о параметрах и возвращаемых значениях функций
5. Для классов описывайте важные атрибуты и методы

Стиль Docstring от Google

Google имеет свой собственный стиль для docstrings. Вот пример:

def разделить(a, b):
"""Разделить два числа.

Аргументы:
a (int): Числитель.
b (int): Знаменатель.

Возвращает:
float: Результат деления.

Поднимает:
ZeroDivisionError: Если b равно 0.
"""
if b == 0:
raise ZeroDivisionError("Нельзя делить на ноль")
return a / b

Стиль Docstring от NumPy/SciPy

Если вы работаете с научными библиотеками Python, вы можете столкнуться со стилем NumPy/SciPy:

def вычислить_среднее(числа):
"""
Вычисляет арифметическое среднее списка чисел.

Параметры
----------
числа : list
Список чисел.

Возвращает
-------
float
Арифметическое среднее входного списка.
"""
return sum(числа) / len(числа)

Стиль Docstring от Sphinx

Sphinx — это популярный генератор документации для Python. Его стиль похож на формат reStructuredText:

def фибоначчи(n):
"""
Генерирует последовательность Фибоначчи до n.

:param n: Количество чисел Фибоначчи для генерации
:type n: int
:return: Список чисел Фибоначчи
:rtype: list
"""
последовательность = [0, 1]
while len(последовательность) < n:
последовательность.append(последовательность[-1] + последовательность[-2])
return последовательность[:n]

Docstring vs Комментарий

Вы, возможно, задаетесь вопросом: "Что такое разница между docstring и обычным комментарием?" Отличная вопрос! Разберем это:

1. Синтаксис: Docstrings используют тройные кавычки, а комментарии — #.
2. Размещение: Docstrings помещаются сразу после определения, а комментарии могут быть где угодно.
3. Назначение: Docstrings объясняют, что делает код, комментарии — как он это делает.
4. Доступность: Docstrings могут быть доступны программно, комментарии — нет.

Вот быстрый пример для иллюстрации:

def добавить(a, b):
"""
Добавляет два числа и возвращает результат.
"""
# Это комментарий, объясняющий, как мы выполняем сложение
return a + b  # Это встроенный комментарий

И это все, друзья! Мы покрыли все аспекты docstrings в Python. Помните, хорошая документация — это как оставлять следы из хлебных крошек для будущего вас (или других разработчиков). Это может показаться лишней работой сейчас, но поверьте мне, вы будете благодарны себе позже!

Вот быстрый справочник по стилям docstring, которые мы рассмотрели:

Стиль	Резюме	Пример
Однострочный	Краткое, однострочное описание	"""Возвращает квадрат числа."""
Многострочный	Подробное описание с параметрами и возвращаемым значением	"""Вычисляет площадь прямоугольника.\n\nПараметры:\n..."""
Google	Включает разделы Args, Returns и Raises	"""Разделить два числа.\n\nАргументы:\n..."""
NumPy/SciPy	Использует разделы Parameters и Returns с более детализированным форматированием	"""Вычисляет арифметическое среднее списка чисел.\n\nПараметры\n----------\n..."""
Sphinx	Использует поля :param:, :type:, :return:, и :rtype:	"""Генерирует последовательность Фибоначчи до n.\n\n:param n: ..."""

Счастливого кодирования, и пусть ваши docstrings всегда будут ясными и информативными!

Credits: Image by storyset