Ответ
В Python существует несколько общепринятых стилей оформления docstrings, которые стандартизируют документирование кода и позволяют инструментам вроде Sphinx автоматически генерировать документацию. Основные из них:
1. Google Style
Отличается высокой читаемостью благодаря четким разделам (Args, Returns, Raises).
def my_function(arg1: int, arg2: str) -> bool:
"""Краткое описание функции в одну строку.
Более подробное описание, если необходимо.
Args:
arg1 (int): Описание первого аргумента.
arg2 (str): Описание второго аргумента.
Returns:
bool: Описание того, что функция возвращает.
"""
return True2. reStructuredText (reST)
Официальный стиль для документации самого Python, широко используется Sphinx. Синтаксис более строгий.
def my_function(arg1: int, arg2: str) -> bool:
"""Краткое описание функции в одну строку.
:param arg1: Описание первого аргумента.
:type arg1: int
:param arg2: Описание второго аргумента.
:type arg2: str
:return: Описание того, что функция возвращает.
:rtype: bool
"""
return True3. NumPy/SciPy Style
Очень подробный и структурированный формат, популярный в научных и data-science библиотеках. Требует точного форматирования.
def my_function(arg1, arg2):
"""Краткое описание функции в одну строку.
Parameters
----------
arg1 : int
Описание первого аргумента.
arg2 : str
Описание второго аргумента.
Returns
-------
bool
Описание того, что функция возвращает.
"""
return TrueВыбор стиля часто диктуется стандартами команды или проекта. Google и NumPy стили особенно популярны благодаря их читаемости и отличной поддержке современными инструментами.
Ответ 18+ 🔞
Да ты посмотри, какие распиздяйства творятся с этими докстрингами! Как будто в трёх соснах заблудились, блядь. Ну ладно, слушай сюда, сейчас разложу по полочкам, а то голова кругом.
Вот есть, сука, несколько главных манер, как эту документацию в функции пихать. Чтобы не просто так, а чтобы потом даже машина могла прочитать и понять, что ты, мудак, имел в виду.
Первый способ — от Гугла. Читается легко, прям как книжка, всё по разделам.
def my_function(arg1: int, arg2: str) -> bool:
"""Краткое описание функции в одну строку.
Более подробное описание, если необходимо.
Args:
arg1 (int): Описание первого аргумента.
arg2 (str): Описание второго аргумента.
Returns:
bool: Описание того, что функция возвращает.
"""
return TrueВторой — этот, reStructuredText. Его сам Питон любит, да и Sphinx на нём собаку съел. Но там, блядь, синтаксис такой, что глазом моргнуть — уже ошибка.
def my_function(arg1: int, arg2: str) -> bool:
"""Краткое описание функции в одну строку.
:param arg1: Описание первого аргумента.
:type arg1: int
:param arg2: Описание второго аргумента.
:type arg2: str
:return: Описание того, что функция возвращает.
:rtype: bool
"""
return TrueНу и третий — для умников, NumPy Style. Эти учёные, блядь, такие зануды — им подавай всё по полочкам, с подчёркиваниями да отступами. Зато красиво, ёпта!
def my_function(arg1, arg2):
"""Краткое описание функции в одну строку.
Parameters
----------
arg1 : int
Описание первого аргумента.
arg2 : str
Описание второго аргумента.
Returns
-------
bool
Описание того, что функция возвращает.
"""
return TrueА выбирать-то что, спрашиваешь? Да обычно в команде решают, всем скопом. Но если по душе — бери Google или NumPy, их сейчас все любят, и инструменты для них — овердохуища. Главное — не начинай писать свою, ёбаную, велосипедную систему, а то потом сам же и обосрёшься, когда через полгода глянешь на свой код и ни хуя не вспомнишь.