Я из будущего оказался чужаком, унаследовавшим мой беспорядок

Больше всего хлопот за весь этот проект мне доставил чужак, который снова и снова наследует мою работу и совершенно не понимает, почему хоть что-то сделано именно так. Это будущее «я» открывает написанные мной файлы, всматривается в принятые мной решения и, как ни старается, не может восстановить ход моих мыслей. Этот чужак, разумеется, — я сам, всего несколько месяцев спустя.

Раньше я считал документацию рутинной повинностью для команд: чем-то, что делают, чтобы другие могли разобраться в твоей работе. Мне понадобилось немало времени, чтобы осознать: самый важный «другой человек», для которого я пишу, — это будущая версия меня самого, у которой не будет ни капли моего нынешнего контекста и которая будет тихо злиться на то, как мало я потрудился оставить после себя.

Иллюзия, будто вы всё запомните

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

Поэтому вы ничего не записываете. С какой стати? И вот именно здесь кроется ловушка, потому что контекст испаряется поразительно, почти яростно быстро. Богатая паутина рассуждений, из-за которой выбор казался неизбежным, растворяется за считаные недели, а остаётся после неё голый выбор — сидит себе, и к нему не привязано ни единой видимой причины.

Возвращение к собственной работе в роли чужака

И вот спустя месяцы я открывал собственный код и натыкался на решения, которые попросту не мог объяснить. Почему это сделано именно так? Почему именно это значение, а не другое? Почему такой порядок, это странное исключение, этот нелепый окольный путь? Какая-то прошлая версия меня знала ответ с полной ясностью. Нынешней же досталась только итоговая выкладка — со всеми рассуждениями, вырванными с корнем.

Это по-настоящему дезориентирующее ощущение — быть чужаком в собственной работе, не доверять выбору того, кого невозможно допросить, и кто при этом — вы сами. Это всё равно что получить в руки последнюю строку длинного доказательства, где стёрт каждый шаг, ведущий к ней. Ответ вот он, прямо перед вами. Вот только нет никакого способа понять, можно ли ему доверять и что сломается, если его изменить.

«Что» — видно; «почему» — исчезло

Вот та асимметрия, которую я совершенно недооценил. Код прекрасно фиксирует, что вы сделали. По самой своей природе он — точная запись предпринятых действий. Но он почти никогда не фиксирует, почему вы это сделали, — а ведь именно «почему» труднее всего восстановить и важнее всего сохранить.

«Что» я всегда смогу восстановить, потому что оно лежит прямо передо мной — бери и перечитывай. «Почему» — замысел, отвергнутые альтернативы, та самая причина, по которой эта странная форма была необходима, — исчезает в тот же миг, как покидает голову, если только я не приложил осознанного усилия его зафиксировать. А без «почему» само «что» почти бесполезно для единственного, что мне на деле нужно сделать: решить, стоит ли это менять и как именно. Запись решений без записи причин — это карта, на которой стёрты все подписи.

Недокументированные решения становятся неприкасаемыми

Самое коварное следствие — то, что происходит с выбором, причина которого забыта. Он становится несущим — так, что вы не можете этого оценить. Вы не знаете, почему он там, а значит, не знаете, что от него зависит, а значит, начинаете бояться к нему прикасаться. И вот он окостеневает — не потому, что он хорош, а потому, что он загадочен.

Система постепенно наполняется этими маленькими замороженными загадками: решениями, потревожить которые теперь страшно всем, включая их собственного автора. Жестокая ирония в том, что я построил их сам, а моя же забывчивость превратила их в нечто, к чему приходится относиться с суеверной осторожностью. Нельзя безопасно менять то, чего не понимаешь, — а оказывается, очень легко не понять то, что написал собственными руками, просто потому, что не записал, почему.

Пишите «почему», а не «что»

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

Фиксировать стоит ровно ту часть, что сама по себе не выживет: «почему». Рассуждение. Альтернативу, которую вы рассмотрели и отвергли, — и почему отвергли. Неочевидное ограничение, вынудившее уродливый выбор. То, что позже покажется ошибкой тому, кто забыл контекст, — особенно когда этот кто-то — вы сами. Одно честное предложение с «почему» сплошь и рядом стоит больше, чем страницы «что», ведь «что» никогда и не было той частью, которой грозила потеря.

Урок поглубже: ваш контекст недолговечен

В основе всего этого лежит ошибка, которую мне сильнее всего нужно было исправить: я верил — ни разу не подвергнув эту веру проверке, — что моё нынешнее понимание попросту сохранится. Оно не сохраняется. Всё, что прямо сейчас кажется кристально ясным у вас в голове, тихо стирается — понемногу, каждый день, — и единственная форма понимания, которая по-настоящему остаётся, — та, которую вы вынесли наружу: вытащили из головы и вложили во что-то, что переживёт память.

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

— Никаких сигналов, никакой доходности, не инвестиционная рекомендация.