«Хороший коммит» и «ваш коммит»: как написать идеальный комментарий в Git / forpes.ru

Главная
«Хороший коммит» и «ваш коммит»: как написать идеальный комментарий в Git

«Хороший коммит» и «ваш коммит»: как написать идеальный комментарий в Git +14

20.09.2023 10:52

beeline_cloud 31 11000 Источник

Привет, Хабр!

Мы в beeline cloud не только создаем современные цифровые продукты, но и обучаем разработке в облаке студентов нашего курса Base Cloud DevOps. Однако выстроить эффективный процесс невозможно без знания основных инструментов. Один из них — система контроля версий Git. Перевели для вас статью, которая поможет извлечь из работы с этой утилитой еще больше пользы.

Когда-то я и не задумывался о существовании каких-то правил для составления комментариев к коммитам, но потом любознательность взяла верх. Мне казалось, что простых сообщений наподобие «добавлена функция 2», «исправлена ошибка на панели навигации» или просто «foo» вполне достаточно. Однако моя уверенность в том, что комментарии к коммитам, как правило, никто не читает, оказалась ошибкой. Хорошо составленные commit messages очень важны, они помогают нам самим в будущем извлечь максимальную пользу из своих стараний и продуманности.

Почему нужно заботиться о написании корректных комментариев?

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

Хорошие коммиты свидетельствуют об умении человека работать в команде — Питер Хаттерер, Linux.

Распространенная в среде разработчиков ошибка – отношение к Git-репозиторию как к обычному хранилищу резервных копий. Беспорядочные коммиты, фиксирующие текущее состояние кода, могут затруднить восприятие хронологии изменений при последующем изучении кодовой базы. Коммиты типа «WIP», «Ушел на обед», «Хватит на сегодня», «Устал как лошадь», «Всем хороших выходных» и «Я первый»" только засоряют ваш Git-лог, затрудняя понимание существенных правок, поскольку ни одно из этих сообщений не представляет никакой дополнительной ценности.

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

Никогда не фиксируйте изменения разных файлов по отдельности

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

Например, я работаю над интернет-магазином. Вот чего мне ❌ не следует делать:

# Отдельно коммитим изменения в header.js

git add header.js git commit -m "Улучшить верстку header.js"

# Отдельно коммитим изменения в footer.js 

git add footer.js

git commit -m "Улучшить дизайн футера"

Таким образом логи очень скоро превратятся в кучу хлама.

Коммиты должны быть четкими, лаконичными, организованными в логические блоки. Например, после завершения верстки макета и проработки шапки и футера будет правильнее объединить изменения перед коммитом:

# Фиксируем изменения в header.js и footer.js

git add header.js footer.js

# Коммитим взаимосвязанные изменения вместе

git commit -m "Улучшить UI: обновить header.js и footer.js"

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

Создайте отдельную ветку для личных коммитов

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

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

commit [commit-hash]

Author: Your Name <your.email@example.com>

Date:   [Timestamp]

   WIP

commit [commit-hash]

Author: Your Name <your.email@example.com>

Date:   [Timestamp]

   Коммичу на всякий случай

commit [commit-hash]

Author: Your Name <your.email@example.com>

Date:   [Timestamp]

   Пора на обед

commit [commit-hash]

Author: Your Name <your.email@example.com>

Date:   [Timestamp]

   Ушел на пописать!

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

Неважно, как — путем корректного именования или договорившись с коллегами напрямую, сделайте очевидным тот факт, что содержимое этой ветки не предназначено для их глаз. Вот хороший пример названия для приватной ветки: private/do-not-use-this.

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

Рассмотрим на живом примере: разработка функции корзины интернет-магазина

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

Вы начали с улучшения CSS для раздела корзины и выполнили соответствующий коммит. По мере продвижения вы внедрили в корзину код на JavaScript, и это привело к еще одному коммиту. В стремлении к совершенству вы заметили проблему с центровкой текста и уделили время доработке CSS, после чего выполнили еще один коммит.

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

Давайте-ка взглянем на логи:

commit [commit-hash-1]

Author: Your Name <your.email@example.com>

Date:   [Timestamp]

   Улучшить CSS для корзины

commit [commit-hash-2]

Author: Your Name <your.email@example.com>

Date:   [Timestamp]

   Добавить в корзину JavaScript функциональность

commit [commit-hash-3]

Author: Your Name <your.email@example.com>

Date:   [Timestamp]

   Исправить ошибки в CSS, ломающие центровку текста в корзине

commit [commit-hash-4]

Author: Your Name <your.email@example.com>

Date:   [Timestamp]

   Поправить баг в работе счетчика товаров корзины

commit [commit-hash-5]

Author: Your Name <your.email@example.com>

Date:   [Timestamp]

   Добавить анимацию к кнопке оформления заказа

Если все эти изменения включить в основную ветку фич наряду с другими фиксами, то процесс рецензирования здорово осложнится.

Как сделать логи более читаемыми

Начните со смены рабочей ветки:

git checkout feature/cart-section

Затем объедините все коммиты из вашей ветки private/do-not-use-this в feature/cart-section с помощью единого коммита:

git merge - squash private/do-not-use-this

После слияния необходимо составить ясный и содержательный комментарий:

# Напишите качественный комментарий

git commit -v -m "Фича: Разработать корзину с анимацией при оформлении заказа

обновлены CSS корзины, исправлены ошибки в выравнивании текста, верстка изменена для улучшения внешнего вида и читаемости"

7 стандартных правил написания идеального комментария к коммиту

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

Правило 1: Ограничьте тему до 50 символов

При формировании темы коммита рекомендуется придерживаться краткости и фокусировки на главном. Строка темы служит кратким изложением цели коммита и в идеале не должна превышать 50 символов.

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

Правило 2: Пишите с заглавной буквы только первую букву темы

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

Правило 3: Не ставьте точку в конце темы

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

git commit -v -m "Создать функциональность корзины с анимацией"

Правило 4: Оставьте между темой и телом комментария пустую строку

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

git commit -v -m "Создать функциональность корзины с анимацией

тело комментария...

"

Правило 5: В теле комментария нельзя писать больше 72 символов в одной строке

Важно пояснить, что важность соблюдение этого правила обусловлена тем, что пользователи командной строки могут столкнуться с усечением текста в строке длиннее 72 символов.

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

git commit -v -m "Создать функциональность корзины с анимацией

улучшены CSS раздела "Корзина", устранены проблемы с выравниванием текста, доработан дизайн

для улучшения внешнего вида

и читабельности."

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

Правило 6: Используйте повелительное наклонение

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

Например, вместо git commit -m "Исправлены баги в верстке" ❌, используйте следующее git commit -m "Исправить баги в верстке" ✔.

То есть, если применить этот коммит, он действительно позволит исправить ошибку на странице макета.

Правило 7: Объясняйте «Что» и «Почему», а не «Как»

Если ограничить смысловую нагрузку комментария вопросами «что сделано?» и «почему сделано?», получится краткое, но информативное объяснение каждого изменения. Разработчики, которым интересно, как был реализован код, могут обратиться непосредственно к кодовой базе. Поэтому подчеркните, что именно было изменено и каковы причины этого изменения. И не забудьте упомянуть, какой компонент или участок кода были затронуты.

Пример из практики: Приемы работы с коммитами, принятые в Angular

Angular является ярким примером эффективного применения комментариев. Команда разработки придерживается специальных префиксов, таких как "chore: , "docs: ," "style: ," "feat: ," "fix: , "refactor: ," и "test: ." Благодаря включению этих префиксов в тему коммита, беглого взгляда на историю достаточно, чтобы понять, какие изменения производились в коде.