Категория

Понятия

Уровень

Начальный

Опирается на

Аннотации типов, главы 4.1–4.5

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

Различать виды документации и выбирать нужный

§1Что называют документацией кода

Документация кода — текст, который объясняет назначение программы и её частей и хранится вместе с исходным кодом. Её читатель — разработчик: тот, кто этот код вызывает, читает и изменяет. Инструкция для пользователя программы пишется отдельно и в исходники не попадает.

Чтобы вызвать функцию из соседнего модуля, нужно знать три вещи:

1. что функция делает;
2. что она принимает и какие значения допустимы;
3. что она возвращает и что будет при неверных данных.

Аннотации из глав 4.1–4.5 закрывают часть этих вопросов: типы параметров и результата теперь записаны в подписи. Остальное аннотация не передаёт — что функция делает, какие значения из допустимого типа подходят, в каких единицах результат и какие ошибки возможны. Эти сведения пишут словами рядом с функцией, и редактор показывает их в месте вызова так же, как типы.

Проект, на котором идёт разбор

Работа продолжается на проекте «Отчёт кафе» из главы 4.1 — теперь со вторым архивом. В нём аннотации уже расставлены, как по итогам практики в главе 4.5, а описаний нет ни одного: их предстоит написать в этой части темы. Если практика по аннотациям сделана, можно продолжать в своей папке; если нет — скачайте второй архив.

1. Распакуйте архив и откройте папку otchet-kafe-start в VS Code.
2. Создайте окружение и установите зависимости: python3 -m venv .venvpy -m venv .venv, затем .venv/bin/pip install -r requirements.txt.venv\Scripts\pip install -r requirements.txt.
3. Запустите проект: .venv/bin/python main.py.venv\Scripts\python main.py. В терминале появится отчёт по смене.

§2Пять видов и их читатели

В проекте на Python встречаются пять видов текста о коде. Они не взаимозаменяемы: у каждого своё место в файлах и свой читатель.

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

§3Комментарий и докстринг: где они оказываются

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

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

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

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

    Raises:
        ValueError: Если список оценок пуст. Среднее по пустому списку
            не определено, поэтому нуль в этом случае не возвращается.
    """
    if not grades:
        raise ValueError("Список оценок пуст")
    # round вызывается один раз в конце: округление каждого
    # слагаемого по отдельности смещает результат
    return round(sum(grades) / len(grades), 2)

Строка в тройных кавычках — докстринг. Она обращена к тому, кто будет вызывать calculate_average из другого модуля: перечислено, что принимается, что возвращается и когда вместо результата будет ошибка. Слова Args:, Returns: и Raises: — разметка разделов; она разобрана в главе 4.8, здесь достаточно прочитать текст под ними. Две строки после знака # — комментарии. Они объясняют выбор внутри тела и нужны тому, кто станет эту функцию править.

Разница проверяется из программы: докстринг доступен через атрибут __doc__, комментария в объекте нет.

>>> from app.services.calculator import calculate_average
>>> print(calculate_average.__doc__.splitlines()[0])
Считает среднюю оценку по списку.

§4Что берёт на себя имя и аннотация типа

Часть работы документации выполняют имя функции и аннотации типов, разобранные в главах 4.1–4.5. Имя calculate_average сообщает действие, аннотация list[int] -> float сообщает типы. Повторять это словами в докстринге не требуется.

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

§5Документация, собранная в сайт

Автоматическая документация — набор HTML-страниц, который программа собирает из исходного кода проекта: проходит по модулям, находит функции и классы, забирает их докстринги и раскладывает по страницам с оглавлением и поиском. Так устроена, например, документация самого Python на сайте docs.python.org.

В Python для этого используется Sphinx — программа сборки документации, которой достаточно указать корень проекта и перечислить модули. Порядок работы такой:

§6Правило документирования в этом курсе

Каждое описание правят вместе с кодом, поэтому описывать всё подряд не требуется. В курсе принято правило по границам модуля: описание обязательно там, где код вызывают снаружи.

Служебные функции с именем, начинающимся с подчёркивания, документируются одной строкой или остаются без докстринга: они вызываются только внутри своего модуля. Проверки, что это правило соблюдено, настраиваются программой — это разобрано в главе 4.10.

§7Частые вопросы

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

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

Итог главы

Документация кода — текст о назначении программы, который хранится вместе с исходниками. В проекте на Python её пять видов: комментарий внутри тела, докстринг у модуля, класса и функции, аннотация типа в подписи, README о проекте целиком и собранный программой сайт. Комментарий адресован тому, кто правит код, и в работающей программе его нет. Докстринг адресован тому, кто вызывает функцию, хранится в атрибуте __doc__ и попадает в подсказку редактора и в собранную документацию. Имя и аннотации сообщают действие и типы, поэтому в докстринг идут ограничения, единицы измерения и поведение при ошибках. В курсе описания обязательны для модулей пакета, публичных функций, классов и мест, где возбуждаются исключения. В следующей главе разобрано, как докстринг устроен: где он должен стоять, как его прочитать из программы и какие правила задаёт стандарт PEP 257.

Категория

Понятия

Уровень

Начальный

Опирается на

Типы в Go, главы 4.1–4.5

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

Различать виды документации и выбирать нужный

§1Что называют документацией кода

Документация кода — текст, который объясняет назначение программы и её частей и хранится вместе с исходным кодом. Её читатель — разработчик: тот, кто этот код вызывает, читает и изменяет. Инструкция для пользователя программы пишется отдельно и в исходники не попадает.

Чтобы вызвать функцию из соседнего пакета, нужно знать три вещи:

• что функция делает;
• что она принимает и какие значения допустимы;
• что она возвращает и в каких случаях вместо результата будет ошибка.

Подпись функции из глав 4.1–4.5 закрывает часть этих вопросов: типы параметров и результатов в Go записаны всегда. Остального подпись не передаёт — что функция делает, какие значения из допустимого типа подходят, в каких единицах результат, когда возвращается ошибка и какая именно. Эти сведения пишут словами перед функцией, и редактор показывает их в месте вызова вместе с подписью.

Проект, на котором идёт разбор

Работа продолжается на проекте «Отчёт кафе» из главы 4.1 — на втором архиве. Код в нём рабочий и собирается, а комментариев документации нет ни одного: их предстоит написать в этой части темы. Если практика 4.5 сделана, можно продолжать в своей папке: исправленный проект совпадает со вторым архивом.

1. Распакуйте архив и откройте папку otchet-kafe-go-start в VS Code — ту, в которой лежит go.mod.
2. Откройте терминал редактора и запустите проект: go run .. В терминале появится отчёт по смене. Команды Go одинаковы во всех системах, окружение создавать не нужно.

§2Пять видов и их читатели

В проекте на Go встречаются пять видов текста о коде. Они не взаимозаменяемы: у каждого своё место в файлах и свой читатель.

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

§3Комментарий и комментарий документации

В Python докстринг и комментарий записываются по-разному: строка в кавычках и строка после #. В Go отдельной записи для документации нет. И то и другое — строки, начинающиеся с //. Комментарием документации строку делает только место:

• комментарий стоит перед объявлением верхнего уровня — package, func, type, var или const;
• между последней строкой комментария и объявлением нет пустой строки.

Такой комментарий называют комментарием документации (doc comment). Всё остальное — комментарии внутри тела функции, комментарии, отделённые пустой строкой, — обычные комментарии: инструменты документации их пропускают. Оба вида видны в функции CalculateAverage из третьего архива:

// CalculateAverage считает среднюю оценку по списку и округляет
// её до двух знаков после запятой.
//
// Для пустого списка возвращается [ErrNoGrades]: среднее по пустому
// списку не определено, поэтому нуль в этом случае не возвращается.
func CalculateAverage(grades []int) (float64, error) {
	if len(grades) == 0 {
		return 0, ErrNoGrades
	}
	sum := 0
	for _, grade := range grades {
		sum += grade
	}
	// Сумма переводится в float64 до деления: деление двух int
	// отбросило бы дробную часть, и среднее 4.4 стало бы 4.
	return math.Round(float64(sum)/float64(len(grades))*100) / 100, nil
}

Пять строк над func — комментарий документации. Он обращён к тому, кто будет вызывать CalculateAverage из другого пакета: что функция делает, как округляет результат и когда вместо среднего вернётся ошибка. Строка из одного // делит текст на абзацы. Запись [ErrNoGrades] в квадратных скобках — ссылка на другое имя пакета; синтаксис комментариев разобран в главе 4.8. Две строки внутри тела — обычный комментарий. Он объясняет выбор внутри функции и нужен тому, кто станет её править.

Разница проверяется командой go doc: она печатает документацию пакета или одного имени прямо в терминале. Выполните её в папке третьего архива:

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

func CalculateAverage(grades []int) (float64, error)
    CalculateAverage считает среднюю оценку по списку и округляет её до двух
    знаков после запятой.

    Для пустого списка возвращается ErrNoGrades: среднее по пустому списку не
    определено, поэтому нуль в этом случае не возвращается.

В ответе — подпись функции и текст комментария документации, заново разбитый на строки длиной около 80 знаков. Комментария из тела функции в ответе нет. Квадратные скобки вокруг ErrNoGrades тоже исчезли: в терминале ссылку показать нечем, а на сайте документации на этом месте будет ссылка.

§4Что берут на себя имя и тип

Часть работы документации выполняют имя функции и типы в подписи. Имя CalculateAverage сообщает действие, подпись (grades []int) (float64, error) сообщает типы и то, что ошибка возможна. Повторять это словами не требуется.

В комментарий идёт то, что из подписи не следует: смысл значения, ограничения на входные данные, когда возвращается ошибка и какая, единицы измерения. Например, что суммы в проекте хранятся в копейках, из типа int не видно, и это место для комментария. Отдельный случай Go — ошибка в результатах: тип error говорит только, что ошибка возможна. Какая именно и в каком случае, сообщает комментарий.

§5Документация, собранная в сайт

Автоматическая документация — набор HTML-страниц, который программа собирает из исходного кода: проходит по пакетам, находит экспортируемые функции, типы, переменные и константы, забирает их подписи и комментарии документации и раскладывает по страницам с оглавлением и поиском. Так устроен сайт pkg.go.dev: на нём документация стандартной библиотеки Go и всех открытых модулей.

В Go для сборки ничего настраивать не нужно: формат комментариев один на весь язык, и инструменты читают его одинаково. Те же страницы, что на pkg.go.dev, программа pkgsite собирает и для своего проекта на своём компьютере. Запустите её в папке третьего архива:

$ go run golang.org/x/pkgsite/cmd/pkgsite@latest

Команда go run с адресом программы и пометкой @latest скачивает последнюю версию pkgsite, собирает и запускает её; в go.mod проекта при этом ничего не добавляется. Первый запуск занимает больше времени: программа скачивается и собирается, следующие запуски берут её из кэша. Когда в терминале появится строка с адресом, откройте в браузере http://localhost:8080 и выберите пакет internal/services. Остановить программу — Ctrl + C в терминале.

§6Правило документирования в этом курсе

Каждое описание приходится поддерживать вместе с кодом, поэтому описывают не всё подряд. В Go граница проходит по видимости имени: описание обязательно там, где код вызывают из другого пакета, то есть у имён с заглавной буквы. Это же правило проверяет revive.

Функции с именем со строчной буквы, например squashSpaces, вызываются только внутри своего пакета. Для них достаточно одной строки, а можно обойтись и без комментария. Проверка, что правило соблюдено, настраивается в главе 4.10.

§7Частые вопросы

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

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

Итог главы

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