Rain Lag

Двухколоночный журнал для кода: простой способ фиксировать, что вы пробовали и что реально сработало

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

Введение

Практически каждый разработчик знает эту ситуацию:

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

Смутно вспоминается, как вы grep-или логи, крутили конфиги или вставляли отладочные print’ы, но точная цепочка действий? Пропала.

Проблема не только в памяти. У большинства из нас просто нет простого, повторяемого способа фиксировать, что мы пробовали и что действительно сработало. Наши заметки — если мы их вообще ведём — это линейный поток сознания, сообщения в Slack или полуготовые TODO, к которым больно возвращаться.

Здесь и помогает двухколоночный журнал для кода.

Это малозатратный формат заметок, который помогает:

  • Разделять действия и попытки от результатов и выводов
  • Относиться к каждой сессии отладки или разработки как к мини-отчёту о баге
  • Формировать краткую, переиспользуемую историю вашей работы
  • Меньше метаться и не повторять одни и те же бесполезные шаги

Если вы видели метод конспектирования по Корнеллу, это будет знакомо — только адаптировано под разработку ПО.

Что такое двухколоночный журнал для кода?

В основе двухколоночного журнала — структурированный формат заметок, который вы ведёте во время сессии программирования или отладки.

Вы делите страницу (или цифровую заметку) на две вертикальные части:

  • Левая колонка: Попытки / Действия — что вы сделали, попробовали или изменили
  • Правая колонка: Итоги / Выводы — что произошло, что вы узнали и к каким решениям пришли

В Markdown это может выглядеть так:

| Попытка / Действие                               | Итог / Вывод                                         |
|--------------------------------------------------|------------------------------------------------------|
| Перезапустил сервис с включённым debug-логированием. | Логи показывают повторяющиеся 500 от auth-сервиса.   |
| Отключил новый фича-флаг `X_BETA_LOGIN`.         | Ошибки исчезли; баг связан с новой логикой логина.  |
| Просмотрел свежий PR по auth #1234.              | Нашёл отсутствующую проверку на null у user profile.|

Или проще:

  • Попытка: Перезапустил сервис с включённым debug-логированием.
    Итог: Логи показывают повторяющиеся 500-ки от auth-сервиса.

  • Попытка: Отключил новый фича-флаг X_BETA_LOGIN.
    Итог: Ошибки исчезли; баг связан с новой логикой логина.

Вы заполняете журнал по ходу работы, а не задним числом по памяти. Это живой лог сессии, а не художественный пересказ.

Почему формат с двумя колонками так хорошо работает

Шаблон простой, но побочные эффекты у него очень сильные.

1. Ясное разделение процесса и результата

Обычно «сырые» заметки по отладке выглядят так:

«Попробовал X. Потом Y. Потом перезапустил. Потом поменял env var. Всё ещё не работает. Может, дело в кэше?»

В двухколоночном формате вы вынуждены явно фиксировать:

  • Что именно вы сделали
  • Что именно произошло из‑за этого

Это разделение сильно упрощает:

  • Замечать, какие действия были шумом и бесполезной активностью
  • Видеть, какие шаги реально продвинули вас к решению
  • Восстанавливать цепочку «причина → следствие» позже

2. Похоже по духу на Cornell Notes

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

  • Основная область заметок
  • Левая колонка для ключевых слов/вопросов
  • Нижний блок для краткого резюме

Идея та же: структура помогает сжатию и осмыслению.

В двухколоночном журнале для кода:

  • Левая колонка — это хронологический поток попыток и действий
  • Правая колонка — ваша сжатая интерпретация и выводы

Такая встроенная структура мягко подталкивает вас не просто «сливать» сырые логи, а по ходу дела конденсировать мышление.

3. Личный «чёрный ящик» отладки

Используя двухколоночный журнал, вы превращаете каждую сессию в мини-отчёт о баге:

  • Что вы подозревали (неявно — по вашим попыткам)
  • Что пробовали и почему
  • Что происходило дальше
  • Что в итоге сработало

Позже, когда вам или коллеге нужно:

  • Воспроизвести проблему
  • Понять корневую причину
  • Задокументировать фикс или написать постмортем

…у вас уже есть краткий, хронологический трейс расследования.

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

Начать можно почти без подготовки. Вот простой рабочий процесс.

Шаг 1: Начните с мини-формулировки проблемы

Вверху заметки запишите:

  • Проблема: Одно предложение, описывающее суть.
  • Контекст: Окружение, ветка, флаги и важные условия.

Пример:

Проблема: API возвращает 500 на `POST /login` в staging.
Контекст: Staging, билд 1.4.2, включён фича-флаг X_BETA_LOGIN.

Это задаёт рамки для всех дальнейших шагов.

Шаг 2: Логируйте каждую попытку по мере выполнения

Для каждого осмысленного действия добавляйте строку или запись:

  • Попытка: что вы сделали (команда, изменение, проверка)
  • Опционально Почему: короткая гипотеза
  • Итог: что вы наблюдали (логи, поведение, метрики)

Пример:

| Попытка / Почему                                      | Итог / Вывод                                           |
|-------------------------------------------------------|--------------------------------------------------------|
| Проверил Nginx-логи для запросов /login.             | Ошибок нет; 500 приходит от upstream-приложения.      |
| Посмотрел application-логи около таймстампа запроса. | Stack trace показывает `NullPointerException` в AuthSvc. |
| Гипотеза: не хватает поля в JWT claims.              |                                                        |
| Залогировал декодированный JWT в AuthSvc.            | Все ожидаемые поля на месте; гипотеза не подтвердилась. |

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

Шаг 3: Отметьте, что на самом деле сработало

Когда вы доходите до фикса или ключевого инсайта, сделайте это визуально заметным:

  • Добавьте ✔ или текстовую метку FIX:
  • Выделите итог жирным
  • Добавьте небольшой блок «Итог» или «Вывод» в конце

Пример:

| Попытка / Почему                                 | Итог / Вывод                                           |
|--------------------------------------------------|--------------------------------------------------------|
| Добавил проверку на null для `user.profile` в AuthSvc. | **✔ Логин проходит; 500-ошибки исчезли.**              |
| Задеплоил фикс в staging и прогнал регрессию.    | **Все тесты зелёные; новых ошибок не наблюдается.**   |

Затем кратко подведите итог:

Вывод: 500-ошибки на /login были вызваны отсутствующей проверкой на null для `user.profile` в AuthSvc. Проявлялось только при включённом фича-флаге beta-логина.

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

Как это улучшает фокус и снижает бессмысленную суету

Когда вы записываете каждую попытку и её результат, вы:

  • В реальном времени видите, когда начинаете крутиться вокруг одних и тех же идей
  • Становитесь более осознанными в том, зачем делаете следующий шаг
  • Меньше полагаетесь на подход «ну давайте на всякий случай всё перезапустим»

Поскольку вы выносите процесс из головы во внешний носитель, вы с меньшей вероятностью будете:

  • Повторять одну и ту же команду по 10 раз в надежде на иной результат
  • Скакать наугад между логами, кодом и дашбордами
  • Терять нить, какие конфиги и флаги вы уже крутили

Двухколоночный формат поддерживает цикличный процесс:

Гипотеза → Попытка → Наблюдение → Вывод

…вместо хаотичного «нажимаем всё подряд и надеемся».

Долгосрочные плюсы: личный QA и инструмент обучения

Если использовать журнал регулярно, он становится не просто набором разрозненных заметок, а вашей личной системой контроля качества и обучения.

1. Выявление повторяющихся ошибок

Просмотрите журналы за несколько недель или месяцев и поищите:

  • Повторяющиеся классы багов (off-by-one, null’ы, гонки, неверные env-переменные)
  • Типичные предположения, которые из раза в раз оказываются неверными
  • Части кодовой базы, которые особенно часто ломаются

Это помогает понять:

  • Где не хватает тестов
  • Где документация неочевидна
  • Какие модули нуждаются в рефакторинге или дополнительных проверках

2. Осознание ваших самых эффективных приёмов

Вы также увидите, какие техники дают наибольшую отдачу:

  • Добавление логов в определённых местах
  • Написание минимальных воспроизводящих тестов
  • Использование конкретных профилировщиков или средств трассировки

Со временем вы сможете собрать личный плейбук по отладке, основанный на том, что действительно работает у вас, а не на абстрактных советах из статей.

3. Улучшение коммуникации в команде

Журнал легко шарить:

  • Вставить в комментарий к задаче в Jira
  • Перекинуть в тред в Slack
  • Приложить к отчёту по инциденту

Вместо: «Я там поковырялся и как‑то починил», вы даёте:

  • Понятную историю того, что было сделано
  • Доказательства корневой причины
  • Готовый нарратив для постмортема

Это повышает доверие и упрощает для других:

  • Воспроизводить инциденты
  • Учиться на вашем подходе
  • Не повторять уже пройденные тупики

Где хранить ваш журнал

Особых инструментов не нужно. Используйте то, что вписывается в ваш рабочий процесс:

  • Отдельный Markdown-файл на задачу прямо в репозитории
  • Специальную заметку «Debug Log» в Notion, Obsidian или Evernote
  • Простой текстовый файл в директории проекта
  • Бумажный блокнот с вертикальной линией посередине страницы

Единственное требование — чтобы журнал был:

  • Быстро доступен в момент начала отладки
  • Удобен для дописывания по ходу работы
  • Поисковым или хотя бы легко пролистываемым потом

Заключение

Двухколоночный журнал для кода — крошечная привычка с непропорционально большим эффектом:

  • Разделяет то, что вы пробовали, и то, что реально сработало
  • Превращает каждую сессию отладки в мини-отчёт о баге
  • Создаёт личную историю ваших ошибок, инсайтов и рабочих стратегий

Не нужен новый инструмент или сложный шаблон. Достаточно начать следующую сессию отладки с двух заголовков:

Попытка / Действие | Итог / Вывод

Заполняйте их по ходу работы. Через несколько недель у вас будет не только меньше повторяющихся ошибок и суеты, но и богатый, ищущийся лог того, как вы на самом деле решаете проблемы.

И в следующий раз, когда снова всплывёт «таинственный» баг, вы начнёте не с нуля, а с просмотра собственной летописи — вашего журнала.