Как работают хорошие комментарии к коммитам
Время — деньги. Время — это дорого. Время вывода продукта на рынок — очень дорого. Время Senior-разработчика — неприлично дорого. Именно поэтому хороший комментарий к коммиту так важен.
“Контекст! Контекст! Полцарства за контекст!”
Чем дольше вы работаете, в большем числе проектов участвуете, видите больше разного кода — тем выше шансы, что вы видели безобразные комментарии к коммитам. Вот часть лога из реальной кодовой базы:
Что это за правки? Почему они так ужасно отформатированы? Почему никто не попытался соблюсти хоть какой-то единый стиль кодовой базы? Кто виноват? “Однажды в далёкой-далёкой галактике мы что-то меняли в нашем коде…”.
Давайте сравним этот лог с недавними коммитами в Spring на Github:
Какие комментарии вам больше понравится читать? Какие — более чёткие и последовательные?
Грамотный комментарий к коммиту— это лучший способ рассказать коллегам о контексте изменений в коде. По диффам можно будет увидеть, что изменилось. Но только комментарий к коммиту расскажет, почему что-то изменилось.
Peter Hutterer однажды сказал:
Любое программное обеспечение — это командный проект. Там будет, как минимум, два разработчика: тот, кто написал исходный код, и тот же самый разработчик, но несколькими неделями или месяцами позже, когда поезд задумки уже давно покинул станцию отправления. Более поздний будет вынужден восстанавливать контекст для конкретной части кода каждый раз, когда появляется новый баг или нужно добавить новую фичу.
Восстанавливать контекст части кода — трудозатратно. Нам придётся это делать, так что давайте направим усилия на то, чтобы минимизировать эти трудозатраты, насколько это возможно. Комментарии к коммитам делают как раз это. В конечном счёте, они показывают, насколько разработчик способен к совместной работе.
Как выглядит хороший комментарий к коммиту
Точного определения идеального коммита не существует. Но мы в компании стараемся следовать известным best practices. Вот некоторые из них.
Три вопроса
Peter Hutterer говорит, что хороший комментарий к коммиту должен отвечать на три вопроса:
- Почему этот коммит необходим? Это может быть исправление бага, добавление новой фичи, улучшение быстродействия, надёжности, стабильности, или просто правка, которую нужно сделать.
- Как коммит решает задачу? Для небольших очевидных правок эту часть можно пропустить. Но даже в этом случае должно существовать высокоуровневое описание использованного подхода.
- На что влияет эта правка? (Помимо очевидных эффектов, речь может идти о соответствии бенчмаркам, побочных эффектах и других последствиях)
Эти три вопроса описывают контекст конкретных изменений в коде. Коллеги, кто будет проверять правки, и остальные, кто увидит этот код — будут смотреть на изменения в заданных рамках; смогут проверить, что подход к решению задачи был выбран верно.
Одно логическое изменение
При прочих равных условиях, хороший коммит должен менять логику кода в одном единственном аспекте. Добавлять одну фичу, исправлять один конкретный баг, делать рефакторинг понятной локальной части кода и так далее. Не следует смешивать изменения из разных областей в едином коммите. Большие изменения стоит разделять и разносить по разным коммитам. Это сильно упростит задачу понимания изменений для тех, кто проверяет код.
Семь правил
Chris Beams выделяет семь правил для написания хороших комментариев к коммитам.
Обратите внимание: всё это уже было описано в разных источниках.
- Ставьте пустую строку между заголовком и описанием.
- Ограничьтесь 50 символами в заголовке.
- Пишите заголовок с большой буквы.
- Не ставьте точку в конце заголовка.
- Используйте повелительное наклонение в заголовке.
- Делайте переносы в описании после 72 символов в строке.
- Используйте описание, чтобы объяснить, что и почему, вместо как.
Например:
Эти правила выглядят просто, но от этого не начинают приносить меньше пользы. Они позволяют команде быть в едином контексте, сохранять целостность продукта, удобно отслеживать изменения, восстанавливать ход рассуждений без того, чтобы каждый раз дёргать автора изменений. Ирония в том, что этим автором можете быть вы сами, несколькими месяцами ранее. Но как давно были сделаны изменения и даже работает ли по-прежнему человек в том же проекте — с хорошими комментариями к коммитам это не важно.
Если свести статью к одной фразе: используйте best practices, чтобы контролировать изменения в коде. Помните: вы не одни в проекте. Позаботьтесь об остальных.
Счастливо попрограммировать!
Автор
Евгений Горбачёв,
Экспресс-консультация
1. Наш специалист свяжется с вами в ближайшее время.
2. В рамках консультации уточним необходимую информацию для анализа вашего проекта.
3. Команда аналитиков и разработчиков подготовят оценку по вашему проекту.
