👾 Как писать комментарии в коде, чтобы потом не было стыдно смотреть людям в глаза

Есть три типа комментаторов в IT:

1. “Угадай, что я имел в виду”

// a = 1 (зачем, почему, кто ты?..)

2. Пишу, потому что так надо

// Increment i Спасибо, Кэп. Я бы в жизни не догадался.

3. Нормальный человек

// Не обновлять кеш, если пользователь в гостевом режиме Вау, спасибо, теперь понятно, почему этот странный if тут живёт!

Чем меньше воды, тем меньше слёз на ревью:

✅ Пиши “что”, “зачем” и “почему” — объяснять очевидное не надо (и так видно).

✅ Поясняй неочевидное решение или хак: “// Так делаем из‑за бага в API v2 — иначе всё падает.”

✅ Не шутить для потомков. Очень смешная шутка про пельмени, но через полгода никому не будет понятно, почему тут этот массив.

✅ Не превращай код в Википедию: документация — вне кода, а в комментариях — только то, что реально помогает сейчас и здесь.

P.S Комментарий — это не исповедь. Пиши так, чтобы твой будущий (уставший) коллега сказал: “Спасибо, что не поленился объяснить!”