Какая система документирования кода используется

Что проверяют

Входит ли документация в вашу обычную работу или появляется за день до релиза. Интервьюера интересует не список инструментов, а то, как у вас связаны docstrings, типы, сгенерированная документация и проверки в CI. Следом часто спрашивают, как вы не даёте документации устареть.

Как отвечать

Опишите слои, начиная с кода:

• docstrings: соглашения описаны в PEP 257. На проект выбирают один стиль: Google, NumPy или поля reStructuredText вида :param name:;
• аннотации типов: сигнатура def load(path: Path, limit: int = 100) -> list[Row] уже документирует половину. Дублировать типы в тексте docstring не нужно, генератор возьмёт их из аннотаций;
• генератор: Sphinx с расширениями autodoc и napoleon (разбирает стили Google и NumPy) и публикация на Read the Docs. Или MkDocs с плагином mkdocstrings, если команде удобнее Markdown. Встроенный pydoc годится для быстрого просмотра, но не для сайта;
• API сервиса: FastAPI строит схему OpenAPI из аннотаций и Pydantic-моделей и сам отдаёт Swagger UI на /docs и ReDoc на /redoc. В Django REST Framework ту же роль играет drf-spectacular;
• проверки: правила D (pydocstyle) в ruff ловят отсутствующие и криво оформленные docstrings, interrogate считает покрытие, а pytest --doctest-modules запускает примеры из docstrings как тесты, так что устаревший пример роняет CI;
• решения: README с запуском проекта и ADR для архитектурных решений, которых из кода не видно.

Если этот вопрос задаёте работодателю вы, ответ многое скажет о команде: «документация на вики, её давно никто не открывал» и «docstrings проверяются в CI» это разные условия работы.

Где спотыкаются

Перечисляют Sphinx, MkDocs и pydoc как равнозначные варианты. Первые два собирают сайт документации, а pydoc просто показывает docstrings.

Пишут docstrings, которые пересказывают имя функции: «Получает пользователя» над get_user. Полезно описывать то, чего нет в сигнатуре: исключения, побочные эффекты, единицы измерения.

Не могут объяснить, как документация остаётся актуальной. Без doctest, проверок в CI и правила ревью «изменилось поведение, обновлён docstring» она устаревает за пару месяцев.