Объясни чужой код так, как объясняют новому разработчику в команде: зачем он существует, а не что делает каждая строка.
Код (замени на свой):
[КОД: def sync_orders(since=None):
since = since or cache.get('last_sync') or '2020-01-01'
raw = api.fetch('/orders', updated_after=since, page_size=500)
for chunk in chunks(raw, 100):
with transaction.atomic():
for o in chunk:
Order.objects.update_or_create(ext_id=o['id'], defaults=map_order(o))
cache.set('last_sync', chunk[-1]['updated_at'])
return len(raw)]
Что я знаю о системе: [КОНТЕКСТ: интернет-магазин на Django, заказы приходят из внешней CRM, я в проекте второй день]
Что нужно:
1. Зачем этот код нужен бизнесу — один абзац, без терминов из самого кода.
2. Разбор по смысловым блокам, а не по строкам: что за что отвечает.
3. Скрытые связи: от чего код зависит снаружи — кеш, транзакции, поля в базе, поведение внешнего API.
4. Что сломается при типичных изменениях: если убрать транзакцию, если поменять размер чанка,
если внешний API отдаст дубли.
5. Три вопроса, которые стоит задать автору, — такие, ответы на которые нельзя вывести из кода.
Отсечка. Не пересказывай синтаксис: «здесь цикл по чанкам, здесь создаётся объект» — это видно
и без объяснения. Не упрощай до «код синхронизирует заказы» и не сглаживай: если в коде есть
опасное место — например, курсор синхронизации двигается после каждого чанка, и при падении на
третьем чанке часть заказов останется незагруженной, — скажи об этом прямо. Не выдумывай назначение
полей, которых нет в коде: чего не видно, то вынеси в пункт 5 как вопрос.
Проверка перед выдачей: убедись, что пункт 4 опирается на код, а не на общие рассуждения о Django —
для каждого сценария укажи строку, из которой следует последствие.
