У меня есть знакомый разработчик. Один. Фулстек, несколько лет опыта, пишет чистый код. Когда я спросила, сколько времени он тратит на документацию, он засмеялся: «Документацию? Это для слабаков».

Не смешно через полгода, когда нужно срочно починить баг, который ты сам написал, а почему — уже не помнишь.

Что такое docstring и почему все его игнорируют

Docstring — это строковая константа в начале функции, класса или модуля, которая описывает что делает код. В Python это первый аргумент функции или первая строка после определения. Выглядит как комментарий, но является частью кода — потому что к нему можно обращаться программно.

Типичная ситуация: функция на 30 строк, через месяц непонятно что она принимает на вход и что возвращает. Комментарии устарели. Исходный разработчик ушёл в отпуск.

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

Python + GPT: docstring за 2 минуты

Я использую связку Python + API OpenAI. Не потому что это единственный способ, а потому что результат предсказуемый. Есть альтернативы — Claude API, локальные модели, но принцип один и тот же: читаем функцию, отправляем в модель, получаем описание.

Простой пример на Python:

import inspect
from openai import OpenAI

client = OpenAI(api_key="ваш-ключ")

def generate_docstring(func):
    source = inspect.getsource(func)
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {
                "role": "system",
                "content": "Ты Python-разработчик. Напиши docstring для функции. Формат: одна строка кратко, потом подробно про параметры и возвращаемое значение. Отвечай на русском."
            },
            {
                "role": "user",
                "content": f"Напиши docstring для этой функции:\n{source}"
            }
        ]
    )
    return response.choices[0].message.content

# Пример использования
def calculate_discount(price, discount_percent, customer_type):
    if discount_percent > 50:
        raise ValueError("Скидка не может быть больше 50%")
    final_price = price * (1 - discount_percent / 100)
    if customer_type == "vip":
        final_price *= 0.9
    return final_price

doc = generate_docstring(calculate_discount)
print(doc)

Запускаем. Результат:

Вычисляет итоговую стоимость с учётом скидки и типа клиента.
Параметры:
price — исходная цена
discount_percent — процент скидки (не более 50)
customer_type — тип клиента (обычный или vip)
Возвращает итоговую цену после применения скидки и бонуса для VIP-клиентов.

Что это даётмал бизнесу

Если вы нанимаете разработчика или работаете с подрядчиком — docstring это не про удобство, это про защиту от рисков. Когда код описан, любой другой разработчик может продолжить работу без погружения в контекст. Это экономит время на онбординг и снижает dependency от одного человека.

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

Как внедрить без боли

Не надо сразу генерировать docstring для всего. Начните с функций, которые:

  • Используются в нескольких местах проекта
  • Содержат бизнес-логику (расчёты, валидации, интеграции)
  • Не менялись последние 3 месяца

Это даёт максимальный эффект при минимальных усилиях. Для новых функций — включите генерацию docstring в definition of done. Не как обязаловку, а как практику. Через месяц посмотрите что изменилось.

Почему это не хайп

LLM для генерации документации — это не магия и не замена инженера. Это инструмент, который снимает рутину. Писать docstring вручную — это как вести бухгалтерию в тетрадке, когда есть Excel. Можно. Но зачем?