Как правильно комментировать коммиты: советы по составлению хороших сообщений

Когда разработчик пишет код, ему кажется, что его изменения очевидны. Однако через несколько дней, а тем более месяцев, понимание сути внесенных изменений может стать сложной задачей. В команде программистов это усугубляется ещё больше: даже если код понятен самому автору, коллегам может быть сложно разобраться в нём без четких комментариев. Сообщения коммитов помогают в этом — они служат своего рода документацией к коду.

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

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

Хорошо написанное сообщение к коммиту помогает другим членам команды быстро понять его суть, помогает избежать необходимости изучать каждую строчку кода для понимания изменений. С другой стороны, плохо написанное или неинформативное сообщение затрудняет анализ изменений, и в конечном итоге тратит время всей команды.

Как составить хорошее сообщение к коммиту?

Чтобы коммит был понятен и полезен другим, сообщение к нему должно быть ясным, информативным и соответствовать некоторым основным правилам.

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

2. Используйте краткие сообщения. Старайтесь не перегружать сообщения излишней информацией, но и не упрощайте их до одной строки. Найдите баланс: важные детали следует указывать, а второстепенные — упускать. Пример: "Исправить баг с загрузкой изображений на главной странице" или "Оптимизировать SQL-запрос в модуле авторизации".

3. Сначала укажите, что было сделано, а затем — почему. Чтобы повысить читабельность, первое предложение должно отвечать на вопрос "Что?", а следующее — на "Почему?" или "Как?" Пример: "Удалить устаревший модуль логирования. Это уменьшит время загрузки на 10%."

4. Избегайте терминов, непонятных для всей команды. Сообщения должны быть написаны так, чтобы любой член команды мог их понять, даже если он не участвовал в разработке данного фрагмента кода. Если вам нужно использовать технический термин, убедитесь, что он общеизвестен или поясните его в комментарии.

5. Не бойтесь пояснить сложные изменения. Когда изменения велики или затрагивают несколько компонентов, добавьте больше деталей в сообщение. Пример: "Рефакторинг функции обработки заказов. Теперь код разбит на отдельные компоненты для улучшения читаемости и тестируемости."

Частые ошибки в сообщениях коммитов и как их избегать

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

1. Слишком короткие или абстрактные сообщения. Сообщения вроде "Исправлено", "Обновлено", "Доработано" или просто "Багфикс" не дают никакой конкретной информации. Такое сообщение не поможет понять, какой именно баг был исправлен или что конкретно было обновлено. Лучше: "Исправить ошибку с анимацией на мобильных устройствах."

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

3. Использование ненужных сокращений. Если сокращения используются часто, это может запутать, особенно если они не являются общепринятыми в вашей компании. Например, сообщения типа "Fixed BG on MFP" (исправлен баг в модуле пользовательских функций) могут стать неясными для других. Лучше: "Исправить баг с отображением на странице функций."

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

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

Часто определённые типы коммитов требуют особого подхода к сообщениям. Рассмотрим несколько популярных сценариев и примеры сообщений к ним.

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

Исправление ошибки
Если вы исправляете ошибку, уточните, где она возникла и как повлияла на работу кода. Пример: "Исправить ошибку отображения карточек продуктов на главной странице. Баг вызывал некорректное отображение карточек при увеличении количества товаров."

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

Обновление документации
Если вы вносите изменения в документацию, обязательно укажите, что изменилось. Пример: "Добавить описание нового API в документацию. Описание включает примеры использования и основные параметры запроса."

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