В мире программирования на Python есть несколько распространенных стилей написания документации или «docstring». Это специальные комментарии, которые описывают, что делает функция или класс и как их использовать.
Пример простого docstring выглядит так:
def add(a, b):
"""
Возвращает сумму двух чисел
"""
return a + b
Здесь строка, заключенная в тройные кавычки, служит docstring для функции add.
Теперь рассмотрим наиболее популярные стили написания docstring.
Освойте Python на курсе от Skypro. Вас ждут 400 часов обучения и практики (достаточно десяти часов в неделю), подготовка проектов для портфолио, индивидуальная проверка домашних заданий и помощь опытных наставников. Получится, даже если у вас нет опыта в IT.
1. Стиль Google
В этом стиле сначала дается общее описание, затем перечисляются аргументы и возвращаемое значение. Пример:
def add(a, b):
"""
Суммирует два числа.
Args:
a (int): Первое число
b (int): Второе число
Returns:
int: Сумма двух чисел
"""
return a + b
2. Стиль reStructuredText
Этот стиль был предложен в документации Python. Он включает в себя использование специальных тэгов.
def add(a, b):
"""
Суммирует два числа.
:param a: Первое число
:param b: Второе число
:return: Сумма двух чисел
"""
return a + b
На курсе Skypro «Python-разработчик» освоите основные инструменты программирования, получите опыт на реальных проектах и сможете стартовать в профессии уверенным новичком. Преподаватели — практикующие программисты с большим опытом, а в центре карьеры помогут составить цепляющее резюме и подготовиться к собеседованию.
3. Стиль NumPy/SciPy
Этот стиль часто используется в научных библиотеках. Он похож на стиль Google, но имеет несколько дополнительных секций.
def add(a, b):
"""
Суммирует два числа.
Parameters
----------
a : int
Первое число
b : int
Второе число
Returns
-------
int
Сумма двух чисел
"""
return a + b
Эти три стиля являются самыми популярными, но выбор стиля зависит от предпочтений разработчика и команды. Главное — чтобы документация была понятной и помогала другим разработчикам понять, как работает код.
Добавить комментарий