Есть два типа программистов.

Первые пишут комментарии в коде:

// Проверяем, существует ли пользователь

Вторые пишут:

// НЕ ТРОГАТЬ. Я НЕ ПОМНЮ, ПОЧЕМУ ЭТО РАБОТАЕТ.

И самое смешное — вторые обычно намного честнее.

Комментарии в коде вообще удивительное явление. Изначально они предназначены для того, чтобы объяснять сложную логику другим разработчикам. Но со временем превращаются в своеобразные послания из прошлого в будущее.

Причём программист из прошлого искренне надеется, что программист из будущего будет достаточно умным, чтобы понять эти послания.

Проблема только в одном:

программист из будущего — это он сам.

И через полгода он уже совершенно другой человек.

«Не удалять»

Классика.

// Не удалять
const temp = calculateSomething();

Почему нельзя удалять?

Неизвестно.

Что делает переменная?

Неизвестно.

Что произойдёт после удаления?

Возможно, ничего. Возможно, сервер загорится.

Поэтому переменная живёт.

Год.

Два.

Пять.

Она уже пережила три рефакторинга, двух тимлидов и переход проекта на новый фреймворк.

А программисты просто обходят её стороной.

Потому что:

«Раз написано «не удалять» — значит, не удалять».

«Я потом разберусь»

Один из самых популярных комментариев в истории программирования:

# TODO: разобраться, почему это работает

Проходит месяц.

Потом год.

Потом приходит новый разработчик и спрашивает:

— А зачем здесь этот костыль?

Ответ:

— Не знаю. Там комментарий есть.

Новый разработчик читает:

# TODO: разобраться, почему это работает

И спрашивает:

— А кто писал?

— Я.

— А что ты хотел сделать?

— Уже не помню.

И вот здесь проект достигает технологического дзена.

Никто не знает, что происходит, но всё работает.

«Очень странный фикс»

Иногда программист понимает, что проблема существует.

Он даже знает, как её исправить.

Но времени нет.

Поэтому появляется:

// TODO: нормально исправить

А рядом:

if (user && user.id && user.id !== 0) {
    // ...
}

Через некоторое время этот if обрастает дополнительными условиями:

if (
    user &&
    user.id &&
    user.id !== 0 &&
    user.active &&
    user.status !== 'deleted' &&
    user.name !== null
) {
    // ...
}

А комментарий всё ещё:

// TODO: нормально исправить

Через два года он превращается в:

// TODO: нормально исправить
// IMPORTANT
// REALLY IMPORTANT
// PLEASE FIX THIS

Но никто не фиксит.

Потому что теперь этот код является частью архитектуры.

«Если ты это читаешь — удачи»

Это уже более продвинутый уровень.

// Если ты это читаешь, значит, ты решил сюда полезть.
// Я тебя предупреждал.

Или:

// Ты сейчас думаешь: "Зачем здесь это?"
// Я тоже так думал.

Ещё лучше:

// Я не знаю, почему это работает.
// Не спрашивай.

А иногда встречается настоящая документация:

// В 2021 году я пытался понять эту функцию.
// В 2022 году другой разработчик пытался понять эту функцию.
// В 2023 году мы решили её не трогать.
// В 2024 году она всё ещё работает.

«Работает — не трогать»

Пожалуй, главный принцип корпоративной разработки.

// Работает.
// Не трогать.

Это не комментарий.

Это охранная сигнализация.

Если вы видите его в коде, у вас есть два варианта:

1. закрыть файл;
2. сделать вид, что вы ничего не видели.

Потому что стоит изменить одну строчку — и внезапно:

• перестаёт работать авторизация;
• исчезают кнопки;
• база данных начинает плакать;
• менеджер пишет в Telegram;
• сервер начинает отдавать 500;
• а вы уже объясняете, почему вчера всё работало.

«Это нужно для Internet Explorer»

Особый вид археологических находок:

/* Fix for IE */

Или:

/* Safari hack */

Или:

/* Не удалять — требуется для старого браузера */

А браузера, ради которого всё это писалось, уже не существует.

Проект давно работает на современных версиях Chrome, Firefox и Safari.

Но код остаётся.

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

«Магическое число»

Иногда комментарий появляется рядом с числом:

setTimeout(update, 137); // 137 — не менять

Почему 137?

Неизвестно.

Почему именно 137 миллисекунд?

Неизвестно.

Почему 138 нельзя?

Потому что 138 уже ломает всё.

Через несколько лет кто-нибудь обязательно спросит:

— Откуда 137?

И начнётся расследование.

Git blame.

Старые коммиты.

Архивы.

Потерянные Jira-задачи.

Старый разработчик.

И выясняется:

«А, это было нужно, потому что браузер иногда не успевал обновить DOM».

Почему комментарий этого не говорил?

Потому что автор думал:

«Я же потом сам вспомню».

«Временное решение»

Самое постоянное в программировании — временное решение.

// Временный костыль.
// Потом сделать нормально.

Через три года:

// Временный костыль.
// НЕ ТРОГАТЬ.

Ещё через два года:

// Критическая часть системы.
// НЕ ТРОГАТЬ.

И наконец:

// LEGACY.
// Работает.
// Лучше вообще не открывать этот файл.

Так рождается технологическое наследие.

«Не знаю, зачем это здесь»

Один из самых честных комментариев:

# Не знаю, зачем это здесь, но без этого падает.

Вот это уже профессиональный подход.

Без притворства.

Без попытки сделать вид, что всё под контролем.

Программист просто честно сообщает будущему себе:

«Брат, я пытался. Дальше твоя очередь».

«Спасибо интернету»

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

Он открывает поисковик.

Находит готовое решение.

Копирует его.

Вставляет в проект.

Всё работает.

И в коде появляется комментарий:

// Нашёл в интернете. Работает — не трогать.

И всё.

Ни ссылки.

Ни объяснения.

Ни малейшего намёка на то, что именно здесь происходит.

Просто:

// «Нашёл в интернете». ...

Проходит три года.

Приходит новый разработчик:

— Почему здесь именно такой код?

— Не знаю.

— А зачем он нужен?

— Не знаю.

— Откуда ты его взял?

— Из интернета.

— А что будет, если удалить?

— Не проверяй.

И вот этот код продолжает работать.

Пять лет.

Десять релизов.

Три смены разработчиков.

Два переезда на новый сервер.

И каждый новый программист просто смотрит на него и думает:

«Ну раз работает — лучше не трогать».

Постепенно случайный кусок кода превращается в священный артефакт проекта.

Никто уже не знает, как он работает.

Зато все знают главное:

если его удалить — станет хуже.

Это уже не комментарий.

Это вера в силу найденного в интернете решения. 😄

«Я знаю, что это ужасно»

Иногда программист прекрасно понимает качество своего решения:

// Да, это ужасно.
// Но дедлайн завтра.

Или:

// Я тоже ненавижу этот код.

Или:

// Это не баг.
// Это решение.

Особенно прекрасный вариант:

// Я знаю можно лучше.
// Просто не надо.

«После этого всё сломалось»

Редкий, но очень полезный комментарий:

// После изменения этой строки сломалась авторизация.
// Почему — неизвестно.
// Поэтому она больше не меняется.

Это уже практически исторический документ.

Потому что программисты иногда оставляют комментарии не для объяснения кода, а для объяснения своих травм.

«Не спрашивай»

Некоторые комментарии лучше любой документации:

// Не спрашивай

Или:

// Нет

Или:

// Пожалуйста не трогай это

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

Когда комментарий становится слишком подробным

Иногда будущему себе оставляют целую инструкцию:

/*
 * Если ты сейчас собираешься удалить этот блок:
 *
 * 1. Не удаляй.
 * 2. Проверь config.js.
 * 3. Потом проверь nginx.
 * 4. Потом очисти cache.
 * 5. Потом перезапусти контейнер.
 * 6. Если не помогло — верни всё обратно.
 * 7. Иди пить кофе.
 */

Это уже не комментарий.

Это письмо из прошлого, написанное человеком, который знал, насколько всё плохо.

Самый страшный комментарий

Но существует комментарий страшнее всех остальных:

// ВСЕ

И всё.

Без описания.

Без даты.

Без автора.

Без объяснения.

Просто:

ВСЕ.

Что сделать?

Неизвестно.

Когда?

Неизвестно.

Зачем?

Неизвестно.

Кем?

Неизвестно.

Зато он появился ещё в 2019 году.

И до сих пор смотрит на вас из исходного кода.

А потом приходит будущий ты

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

Мы пишем:

// Тут всё очевидно

А через полгода открываем файл и думаем:

«Какой идиот это написал?»

Проверяем Git.

Автор:

мы.

Дата:

вчера.

И вот тогда приходит главное осознание профессии:

самый загадочный разработчик в проекте — это ты из прошлого.

Он принимал решения.

Он знал архитектуру.

Он понимал бизнес-логику.

Он почему-то выбрал именно 137.

А теперь он исчез.

Оставил только несколько комментариев, пару ВСЕ и загадочную переменную temp2_final_new.

И поэтому, если сегодня вы пишете код и оставляете комментарий:

// Не трогать. Работает

сделайте одолжение своему будущему себе.

Добавьте хотя бы ещё одну строчку:

// Не трогать. Работает.
// Как и почему, я тоже не знаю.

Через полгода вы будете ему благодарны. 😄