Категория

Синтаксис и стандарт

Уровень

Начальный

Опирается на

Глава 4.6, модули и пакеты

Зачем это знать

Писать докстринги так, чтобы их видели инструменты

§1Определение и место в файле

Докстринг — строковый литерал, стоящий первой инструкцией в модуле, классе, функции или методе. Python сохраняет такую строку в атрибуте __doc__ соответствующего объекта. Пишут докстринг в тройных кавычках: они позволяют занять несколько строк и оставляют внутри одинарные и двойные кавычки без экранирования.

Место в файле решает, сохранится строка или пропадёт. Ниже одна и та же функция с одной и той же строкой, сдвинутой на строку ниже.

def normalize_name(name: str) -> str:
    """Приводит имя официанта к виду «Фамилия Имя»."""
    cleaned = " ".join(name.split())
    return cleaned.title()

>>> normalize_name.__doc__
'Приводит имя официанта к виду «Фамилия Имя».'

def normalize_name(name: str) -> str:
    cleaned = " ".join(name.split())
    """Приводит имя официанта к виду «Фамилия Имя»."""
    return cleaned.title()

>>> print(normalize_name.__doc__)
None

Разница видна только из программы: во втором случае normalize_name.__doc__ равен None. По внешним признакам такое место отличается от первого пустой подсказкой редактора, и ошибки при запуске не возникает.

§2Где Python хранит докстринг

Докстринг доступен через атрибут __doc__ у любого объекта, который его имеет: модуля, класса, функции, метода. Атрибут — обычная строка, с ней можно работать как с любой другой.

>>> from app.utils.text import normalize_name
>>> normalize_name.__doc__
'Приводит имя официанта к виду «Фамилия Имя».'
>>> import app.utils.text
>>> app.utils.text.__doc__
'Работа с именами и строками отчёта.'
>>> print(len.__doc__)
Return the number of items in a container.

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

У многострочных докстрингов в __doc__ сохраняются и отступы, которыми текст был выровнен в файле. Чтобы получить текст без общего отступа, применяют inspect.getdoc:

>>> import inspect
>>> from app.services.calculator import calculate_average
>>> print(inspect.getdoc(calculate_average))
Считает среднюю оценку по списку.

Args:
    grades: Оценки от 2 до 5, список не должен быть пустым.

Returns:
    Среднее значение, округлённое до двух знаков.

Raises:
    ValueError: Если список оценок пуст. Среднее по пустому списку
        не определено, поэтому нуль в этом случае не возвращается.

§3help и подсказка редактора

Встроенная функция help() печатает справку об объекте: подпись, докстринг и, для модулей и классов, перечень их содержимого. Она работает только на том, что записано в коде, и никаких описаний не добавляет.

>>> help(calculate_average)
Help on function calculate_average in module app.services.calculator:

calculate_average(grades: list[int]) -> float
    Считает среднюю оценку по списку.

    Args:
        grades: Оценки от 2 до 5, список не должен быть пустым.

    Returns:
        Среднее значение, округлённое до двух знаков.

    Raises:
        ValueError: Если список оценок пуст. Среднее по пустому списку
            не определено, поэтому нуль в этом случае не возвращается.

На модуле help() печатает его докстринг и перечень функций с первыми строками их описаний. Так проверяют, что описания на месте: у функции без докстринга в выводе остаётся одна подпись.

VS Code показывает то же самое при наведении указателя на имя функции в месте её вызова: всплывает подпись с аннотациями и текст докстринга. Подсказка вызывается и с клавиатуры — CtrlCmd + K, затем CtrlCmd + I. Пустая подсказка означает, что докстринга нет или он стоит не на первом месте.

Разница между кодом с описаниями и без них видна в одной и той же подсказке. Сначала проект, в котором докстрингов ещё нет, следом тот же вызов после того, как описания написаны.

§4Однострочный докстринг

Однострочная запись применяется, когда назначение выражается одним предложением, а параметры понятны из имён и аннотаций. Правила записи такие:

• Кавычки и текст на одной строке: """Текст."""
• Предложение заканчивается точкой.
• Пустых строк до и после нет.
• Описывается действие функции: «Возвращает…», «Считает…», «Записывает…».

def format_kopeks(kopeks: int) -> str:
    """Переводит сумму в копейках в строку вида «1 250,00 ₽»."""
    return f"{kopeks / 100:,.2f} ₽".replace(",", " ").replace(".", ",")


def format_title(text: str, width: int = 40) -> str:
    """Центрирует заголовок отчёта по заданной ширине."""
    return text.center(width, "=")

§5Многострочный докстринг

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

def load_orders(path: Path) -> list[Order]:
    """Читает заказы из CSV-файла.        # краткая строка: одно предложение

    Имена официантов в файле записаны по-разному, поэтому здесь они
    приводятся к одному виду: по ним потом группируются заказы.
                                        # пустая строка отделяет разделы
    Args:
        path: Путь к файлу с колонками waiter и kopeks.

    Returns:
        Список заказов в порядке следования строк файла.

    Raises:
        FileNotFoundError: Если файла по указанному пути нет.
        ValueError: Если в колонке kopeks не целое число.
    """                                 # кавычки на отдельной строке

Комментарии справа в примере добавлены для разбора и в коде не пишутся. Порядок частей одинаков во всех форматах из главы 4.8, различается только запись разделов.

§6Правила PEP 257

PEP 257 — документ стандарта Python, описывающий оформление докстрингов. Он задаёт общие правила записи: в каких кавычках, где переносы, о чём первая строка. Разметку разделов он не определяет; форматы из главы 4.8 надстраиваются над этими правилами.

Про первую строку PEP 257 требует описывать действие функции, и в англоязычных проектах это записывают повелительной формой: Return the list of orders. В русском тексте тот же смысл передаётся формой третьего лица: «Возвращает список заказов». В курсе принята эта форма, и она должна быть одинаковой во всём проекте.

§7Докстринг модуля и пакета

Докстринг модуля — первая строка файла, до импортов. Он называет, за что файл отвечает, и попадает в раздел DESCRIPTION при вызове help() на модуле.

"""Заказы: чтение из CSV и расчёты по ним.

Модуль работает только с данными заказов и ничего не печатает.
Форматирование отчёта — в app/utils/formatter.py.
"""

import csv
from pathlib import Path

У пакета докстринг пишется в файле __init__.py: этот файл представляет пакет целиком. В нём указывают назначение пакета и перечень того, что он предоставляет наружу.

"""Служебный слой: расчёты и чтение данных.

Пакет содержит модули calculator и orders. Функции этих модулей
вызываются из main.py и не зависят от способа вывода.
"""

Перечислять внутри докстринга все функции модуля не требуется: их список help() и сборщик документации получают из самого кода.

§8Докстринг класса и метода

Докстринг класса стоит первой строкой после class и описывает, что представляет объект этого класса. Атрибуты перечисляют в отдельном разделе. У методов свои докстринги, по тем же правилам, что у функций.

class Shift:
    """Смена кафе: заказы одного рабочего дня.

    Объект накапливает заказы и считает по ним итоги. Заказы хранятся
    в порядке добавления.

    Attributes:
        day: Дата смены.
        orders: Добавленные заказы в порядке поступления.
    """

    def __init__(self, day: date) -> None:
        """Создаёт пустую смену на указанную дату."""
        self.day = day
        self.orders: list[Order] = []

    def add(self, order: Order) -> None:
        """Добавляет заказ в конец списка смены.

        Args:
            order: Заказ с уже нормализованным именем официанта.
        """
        self.orders.append(order)

    def total_kopeks(self) -> int:
        """Возвращает выручку смены в копейках; у пустой смены — 0."""
        return sum(order.kopeks for order in self.orders)

Описание того, что объект собой представляет, идёт в докстринг класса, а перечень полей — в раздел Attributes:. Описание создания и проверок при создании относится к __init__. Здесь проверок нет и параметр один, поэтому у __init__ хватает одной строки.

Как этот докстринг выглядит в справке, показано в главе 4.9, случай 10: help(Shift) печатает описание класса, раздел Attributes и следом перечень методов с их описаниями.

§9Восемь ошибок

§10Мини-практика: пять минут

Шаги выполняются на стартовом архиве проекта темы из главы 4.6.

1. Распакуйте архив, откройте папку в VS Code и найдите файл app/services/calculator.py. Добавьте докстринг модуля первой строкой файла, до импортов.
2. Добавьте однострочный докстринг функции calculate_average.
3. Запустите python -i -c "import app.services.calculator as c" и выполните help(c). В выводе должны быть докстринг модуля и список функций.
4. Выполните print(c.calculate_average.__doc__) и сверьте текст с файлом.
5. Перенесите докстринг функции на строку ниже, после первой инструкции тела, и повторите предыдущую команду. Вывод — None.
6. Верните докстринг на место. Наведите указатель на вызов функции в main.py: в подсказке появился текст описания.

§11Проверьте себя

§12Шпаргалка по главе

Итог главы

Докстринг — строковый литерал, стоящий первой инструкцией в модуле, классе, функции или методе. Python сохраняет его в атрибуте __doc__, откуда его читают help(), модуль inspect, подсказка редактора и сборщик документации. Строка, стоящая после первой инструкции тела, докстрингом не становится, и ошибки при этом не возникает: описание не доходит до читателя. Однострочная запись годится, когда назначение выражается одним предложением. Многострочная состоит из краткой строки, пустой строки и разделов о параметрах, результате и исключениях; закрывающие кавычки стоят на отдельной строке. Эти правила задаёт PEP 257, а разметку разделов — форматы, которые разобраны в следующей главе: одна и та же функция записана в них четырьмя способами.

Категория

Синтаксис и правила

Уровень

Начальный

Опирается на

Глава 4.6, пакеты Go

Зачем это знать

Писать комментарии так, чтобы их видели инструменты

§1Определение и место в файле

Комментарий документации — комментарий, который стоит непосредственно перед объявлением верхнего уровня: package, func, type, var или const. Инструменты Go — go doc, gopls, pkgsite — считают его описанием этого объявления. Записывают его строками, начинающимися с //; запись /* … */ тоже допустима, но в коде на Go почти не встречается.

Место в файле решает, попадёт ли текст в документацию. Ниже одна и та же функция из internal/utils/text.go с одним и тем же комментарием: в первой вкладке он стоит вплотную, во второй его отделяет пустая строка.

// NormalizeName приводит имя официанта к виду «Фамилия Имя».
func NormalizeName(name string) string {

package utils // import "example.com/otchet-kafe/internal/utils"

func NormalizeName(name string) string
    NormalizeName приводит имя официанта к виду «Фамилия Имя».

// NormalizeName приводит имя официанта к виду «Фамилия Имя».

func NormalizeName(name string) string {

package utils // import "example.com/otchet-kafe/internal/utils"

func NormalizeName(name string) string

Разница видна только инструментам: текст в файле на месте, и человек, открывший файл, его прочитает. Тот, кто вызывает функцию из другого пакета и смотрит подсказку, описания не увидит.

§2Команда go doc

Команда go doc печатает документацию в терминале. Ей передают путь к пакету и, если нужно, имя внутри него. Путь к пакету своего модуля начинается с ./: ./internal/utils — пакет в этой папке. Пакеты стандартной библиотеки называют по имени: strings, fmt. Все команды ниже выполнены в папке третьего архива.

На пакете go doc печатает его комментарий и перечень того, что пакет предоставляет. Так проверяют, что описание пакета на месте:

$ go doc ./internal/services
package services // import "example.com/otchet-kafe/internal/services"

Package services — служебный слой: чтение данных и расчёты.

Функции пакета работают только с данными и ничего не печатают.

var ErrNoGrades = errors.New("список оценок пуст")
var ErrNoOrders = errors.New("список заказов пуст")
func CalculateAverage(grades []int) (float64, error)
func GradeBounds(grades []int) (low, high int, err error)
func LoadOrders(path string) ([]domain.Order, error)
func ReadRows(path string) iter.Seq2[map[string]string, error]
func SaveReport(path string, lines []string) (int, error)
func SortOrdersInPlace(orders []domain.Order)
type WaiterRevenue struct{ ... }
    func RevenueByWaiter(orders []domain.Order, top int) ([]WaiterRevenue, error)

Первая строка — имя пакета и путь, по которому его импортируют. Ниже — комментарий пакета, затем переменные, функции и типы. RevenueByWaiter напечатана с отступом под типом WaiterRevenue: go doc относит к типу функции, которые возвращают значения этого типа, — так их проще найти. Описаний функций в этом перечне нет: чтобы прочитать описание, передают имя.

С флагом -all печатается всё сразу. Так выглядит небольшой пакет ui:

$ go doc -all ./internal/ui
package ui // import "example.com/otchet-kafe/internal/ui"

Package ui выводит готовый отчёт пользователю.

FUNCTIONS

func PrintReport(lines []string)
    PrintReport печатает готовый отчёт в консоль построчно.

    Функция только печатает: расчёты и форматирование выполняются до вызова,
    в пакетах services и utils.

Текст комментария go doc заново разбивает на строки по ширине около 80 знаков, поэтому переносы в выводе не совпадают с переносами в файле. Абзацы при этом сохраняются: их разделяет строка из одного //. Через ту же команду читаются описания стандартной библиотеки: go doc strings.Fields печатает комментарий из исходников Go, записанный по тем же правилам, что и комментарии проекта.

§3Подсказка редактора

VS Code показывает комментарий документации при наведении указателя на имя в месте вызова: под подписью идёт текст комментария. Подсказка вызывается и с клавиатуры — CtrlCmd + K, затем CtrlCmd + I. Пустая подсказка означает, что комментария нет или он стоит не вплотную.

Разница видна в одной и той же подсказке. Сначала второй архив, в котором комментариев ещё нет, следом третий, задокументированный. В обоих курсор стоит на вызове RevenueByWaiter в main.go.

§4Короткий комментарий

Короткая запись применяется, когда назначение выражается одним предложением, а параметры понятны из имён и типов. Правила записи такие:

• первое слово — имя того, что описывается: // TodayLabel возвращает…;
• дальше — полное предложение о действии: «возвращает…», «считает…», «записывает…»;
• предложение заканчивается точкой;
• между комментарием и объявлением нет пустой строки.

// TodayLabel возвращает текущую дату в виде «21.09.2026» для шапки отчёта.
func TodayLabel() string {

// NewShift создаёт пустую смену на указанную дату.
func NewShift(day time.Time) *Shift {

// Add добавляет заказ в конец списка смены.
func (s *Shift) Add(order Order) {

Почему комментарий начинается с имени: строка комментария тогда понятна и без объявления рядом. Поиск по файлам проекта выдаёт отдельные строки, и строка // TodayLabel возвращает текущую дату… сама сообщает, о какой функции речь. Первое слово-имя проверяет revive — правило разобрано в §9.

§5Подробный комментарий

Подробная запись нужна, когда у параметров есть ограничения, результат требует пояснения или функция возвращает ошибку. Устройство такое: первое предложение о действии, пустая строка комментария //, затем абзацы с подробностями.

// LoadOrders читает заказы из файла смены с колонками waiter и kopeks.   ← первое предложение
//                                                                         ← граница абзаца
// Заказы возвращаются в порядке строк файла. Ошибка возвращается, если
// файла нет или в колонке kopeks записано не целое число.
func LoadOrders(path string) ([]domain.Order, error) {

Пометки со стрелками справа добавлены для разбора и в коде не пишутся. В отличие от Python, в Go нет разделов вроде Args: и Returns:. Параметры, результат и ошибки описывают обычными предложениями, называя параметры по имени: «параметр top ограничивает…», «для пустого списка возвращается [ErrNoOrders]». Так написаны и комментарии стандартной библиотеки — например, у strings.Fields.

§6Правила Go Doc Comments

Go Doc Comments — руководство на сайте go.dev, которое описывает, как пишутся комментарии документации и как инструменты их показывают. В Go оно одно на весь язык: отдельных форматов, как у Python, нет. Основные правила:

Про форму первого предложения. В англоязычном коде Go пишут // LoadOrders reads…: имя, затем глагол в третьем лице. В русском тексте та же форма: «LoadOrders читает…», «Add добавляет…». В курсе она принята для всего проекта. Если имени нет или оно не первое, revive выдаёт замечание.

§7Комментарий пакета и программы

Комментарий пакета стоит над строкой package и начинается словами Package имя. Он называет, за что отвечает пакет, и печатается первым в выводе go doc на пакете. У пакета обычно несколько файлов, а комментарий пакета пишут в одном из них. Если написать его в двух файлах, инструменты склеят оба текста в один.

// Package services — служебный слой: чтение данных и расчёты.
//
// Функции пакета работают только с данными и ничего не печатают.
package services

В пакете services четыре файла, и комментарий пакета есть только в calculator.go; в importer.go, orders.go и report_file.go строка package services стоит без комментария. В больших пакетах для комментария заводят отдельный файл doc.go, в котором кроме комментария и строки package ничего нет: так его проще найти.

У пакета main комментарий описывает программу: что она делает и как её запустить. Слов Package main в нём не пишут — читателю программы они ничего не сообщают.

// Программа «Отчёт кафе» читает файл смены, считает выручку
// по официантам и печатает отчёт в консоль.
//
// Запуск из папки с go.mod:
//
//	go run .
package main

Строка // go run . начинается с табуляции после //. Так в комментарии записывают блок кода или команду: инструменты покажут его моноширинным шрифтом и не станут переносить по словам. Этот и другие элементы разметки разобраны в главе 4.8. Перечислять в комментарии пакета все его функции не нужно: их перечень go doc и pkgsite получают из самого кода.

§8Тип, поля и методы

Комментарий типа стоит над словом type и описывает, что представляет значение этого типа. Поля структуры описывают коротким комментарием в конце строки поля — отдельного раздела, как Attributes: в Python, нет. У методов свои комментарии, по тем же правилам, что у функций.

// Order — один заказ из файла смены.
//
// Создавать заказ нужно через [NewOrder]: она проверяет сумму
// и приводит имя официанта к виду «Фамилия Имя».
type Order struct {
	Waiter string // имя официанта в виде «Фамилия Имя»
	Kopeks int    // сумма заказа в копейках, неотрицательная
}

// NewOrder создаёт заказ с проверкой данных.
//
// Имя официанта нормализуется функцией [utils.NormalizeName].
// Если сумма отрицательная, возвращается [ErrNegativeKopeks].
func NewOrder(waiter string, kopeks int) (Order, error) {

В комментарии типа сказано, что заказ представляет и как его правильно создавать. Единицы суммы — копейки — записаны у поля Kopeks: из типа int их не видно. Проверки при создании описаны у конструктора NewOrder: в нём они и выполняются.

Так этот текст печатает go doc: объявление типа вместе с комментариями полей, затем комментарий типа и функции, которые его создают.

$ go doc ./internal/domain Order
package domain // import "example.com/otchet-kafe/internal/domain"

type Order struct {
	Waiter string // имя официанта в виде «Фамилия Имя»
	Kopeks int    // сумма заказа в копейках, неотрицательная
}
    Order — один заказ из файла смены.

    Создавать заказ нужно через NewOrder: она проверяет сумму и приводит имя
    официанта к виду «Фамилия Имя».

func NewOrder(waiter string, kopeks int) (Order, error)

§9Восемь ошибок

Первые две ошибки получены на проекте темы: замечания revive в таблице — его настоящий вывод. Ни одна из восьми ошибок не мешает сборке: компилятор комментарии не читает. Их находят программой проверки из главы 4.10 и чтением на ревью.

§10Мини-практика: пять минут

Шаги выполняются на втором архиве проекта из главы 4.6.

1. Откройте файл internal/services/calculator.go. Добавьте над строкой package services комментарий пакета, начиная со слов // Package services.
2. Добавьте короткий комментарий над func CalculateAverage, начиная с имени функции.
3. Выполните в терминале go doc ./internal/services. В выводе должен появиться комментарий пакета.
4. Выполните go doc ./internal/services CalculateAverage и сверьте текст с файлом.
5. Вставьте пустую строку между комментарием и func и повторите предыдущую команду. В выводе останется одна подпись.
6. Уберите пустую строку. Откройте internal/services/calculator_test.go и наведите указатель на вызов CalculateAverage в первом тесте: в подсказке появился текст описания.

§11Проверьте себя

§12Шпаргалка по главе

Итог главы

Комментарий документации — комментарий вплотную над объявлением верхнего уровня. Его читают go doc, подсказка редактора и pkgsite; комментарий, отделённый пустой строкой, становится обычным, и ошибки при этом не возникает: описание просто не доходит до читателя. Первое предложение начинается с имени описываемого и сообщает действие. Подробности идут абзацами через строку //; разделов для параметров и результата в Go нет, их описывают предложениями. Комментарий пакета начинается словами Package имя, поля структуры описывают в конце строки. В следующей главе разобрана разметка внутри комментария — ссылки, списки, блоки кода — и примеры, которые проверяются запуском.