Как писать понятные сообщения к изменениям

Кто это вообще читает

Три категории людей:

• Вы через полгода, когда будете выяснять, почему тут так сделано.
• Коллеги, разбирающие ваши изменения.
• Работодатели, открывшие ваш репозиторий перед собеседованием.

Последнее многие не учитывают. История изменений — часть портфолио, и по ней видно, как человек работает.

Что не так с «fix»

Сообщение должно отвечать на вопрос «что изменилось и зачем». «fix», «update», «правки», «доработки» не отвечают ни на что.

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

Схема

Первая строка — что сделано, до семидесяти символов. Глагол в прошедшем или настоящем времени, без точки в конце.

Плохо:

fix
исправления
работа над формой

Хорошо:

добавил проверку суммы в форме расхода
исправил падение при пустом списке заметок
убрал лишний запрос к базе в списке заказов

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

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

Про принятые обозначения

Во многих командах принято помечать тип изменения в начале:

feat: добавил экспорт расходов в файл
fix: исправил подсчёт итога за месяц
docs: описал запуск проекта в README

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

Как разбивать работу

Правило: одно изменение — одна законченная мысль.

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

Хорошо: три отдельных сохранения.

Как этого добиться: сохраняйте, когда закончили кусок, а не когда закончили день. Если поймали себя на желании написать «и ещё поправил» — это два изменения.

Чего не должно быть в сообщениях

• Ругательств и эмоций. Даже если код правда ужасен.
• Личных данных и паролей.
• Пустых сообщений вроде точки или пробела.
• Сообщений на трёх языках вперемешку. Выберите один и придерживайтесь.

Что это даёт на собеседовании

Работодатель, открывший ваш репозиторий, видит по истории: работал человек регулярно или сделал всё за одну ночь, умеет ли разделять работу на части, объясняет ли свои решения.

Это бесплатное преимущество: писать внятные сообщения не сложнее, чем невнятные, а разница в впечатлении заметная.