Лог комита: зачем он нужен на самом деле?

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

Очень часто переход от мышления "я сохранил файл - код зафиксирован" к мышлению "я сделал комит - код зафиксирован" натыкается на то, что процесс комита требует написания лога комита. Первое решение - оставить лог пустым или написать что-то из:

• "фикс бага";
• "закомитил всё, что сделал";
• "тестовый комит";
• "исправил опечатку";
• и т.п.

Почему это плохо?

Один ответ на этот вопрос заключается в том, что лог комита является документацией на код и на изменение. Идеальный лог комита должен позволять по истории изменений конкретного файла понять, что произошло в каждой ревизии, не заглядывая в само изменение (дифф файла). Лог комита может содержать дополнительную мета-информацию: номер тикета, имя человека, который провел code-review, ссылки на другие комиты и т.п.

Пытаясь удовлетворить приведенным выше требованиям разработчик часто возьмет заголовок тикета и впишет его в лог комита. Однако, чаще всего тикет формулируется в терминах не разработки, а исходной задачи, например: "Сделать отступ 10 пикселей между блоками А и Б". Такая фраза в качестве лога комита в CSS-файл сообщает информацию о изменении, но какую информацию она дает читающему такой лог? Ведь на самом деле, например, был создан новый CSS-класс с именем таким-то, из другого CSS-класса был удален какой-то стиль и т.п. То есть само по себе изменение описывается на другом языке, не на языке менеджера проекта. Было бы полезно иметь и то, и другое представление комита, например:

Сделать отступ 10 пикселей между блоками А и Б: был 
создан новый класс blockC, из класса blockA удалено 
padding-bottom: 0.5em, т.к. все paddingи перенесены в 
класс blockC.

Тикет: #1734

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

Что нового дает такой лог комита по сравнению с логом: "закомитил CSS-фикс"?

Мне кажется, основное преимущество состоит в вербализации изменения. И оно даже не для читающего этот лог когда-то, а для пишущего. Процесс программирования сегодня особенно в web-разработке очень быстрый. Мы не пишем псевдо-код, редко рисуем диаграммы, часто между постановкой задачи и выкладкой нового кода на рабочие сервера может пройти несколько часов. За эти часы код не может пройти естественные этапы: отлежаться "пару дней", чтобы автор мог вернуться к нему с "незамутненным взглядом", не успеет пройти code-review, другие разработчики не успеют получить его из репозитория, и т.п. В то время как основная масса кода оказывается лучше изучена и протестирована за время от одного релиза до другого. Но и очень часто мы допускаем ошибки просто в силу того, что упускаем из вида важные детали из-за каких-то еще причин: отсутствия опыта, усталости, частого переключения между задачами и т.п. Как обеспечить качество разработки в таких условиях?

Процесс программирования невербален. Он начинается с задачи, поставленной не в терминах разработчика, а в терминах заказчика. И часто эта формулировка каким-то образом трансформируется в уме разработчика в конкретное решение в терминах языка программирования без фиксации на словах промежуточных результатов. Код на языке программирования не содержит формулировки задачи в терминах разработчика, он содержит некое решение, которое, возможно решает исходную задачу, возможно привносит некоторые ошибки (баги).

Код написан, и вот сейчас подошло время фиксировать изменение в репозитории, а значит, писать лог комита! И это самое время попробовать вербализировать своё изменение на естественном языке. Если ограничиться отпиской вида "фикс бага" или скопировать часть фразы из тикета, процесс вербализации не включается, т.к. мы ничего не формулируем. А давайте попробуем на хорошем русском языке сформулировать что же именно мы изменили, почему мы изменили, какие это имеет последствия (возможно) для другого кода? Для того, чтобы сформулировать точно, что же именно мы изменили, потребуется просмотреть дифф текущего изменения, что замечательно, это фиксирует внимание на каждом блоке изменений в попытке рассмотреть каждую строчку кода, резюмировать изменения общей идеей, не упуская при этом важных деталей. Этот дополнительный взгяд на дифф изменений позволяет найти как простые технические ошибки, как, например, отсутствие докблока, так и нетривиальные - забытые отладочные операторы, изменения, сделанные временно в процессе программирования, "меньше" вместо "больше" и т.п.

Процесс формулирования самого лога комита на естественном языке позволяет найти логические ошибки в изменении, когда мы понимаем, что наше исправление неполно, избыточно, противоречиво, не решает исходную задачу и т.п. Магия состоит именно в попытке сформулировать рассказ об изменении, т.е. рассказать о своем изменении другим разработчикам. Наверное, многие замечали, что иногда достаточно подойти за помощью к другому разработчику и рассказать о проблеме, чтобы тут же в голове появилось решение. Именно процесс вербализации нашей потусторонней, фантастической деятельности программистов, заключающейся в переводе мыслей заказчика в фразы языка программирования, позволяет осознать суть сделанных изменений и найти скрытую ошибку в коде. Поэтому... пишите хорошие логи комитов!