Изменения в коммите (дифф) рассказывают, что изменилось. Единственный способ объяснить, зачем эти изменения и какая от них польза — комментарий к коммиту. Полезный комментарий описывает не изменения в коде, а их результат в мире разработчика:

7279242f add <div> wrap
# Плохо — это мы и в диффе видим. Зачем добавляли? Что исправляли?
 
7279242f fix Firefox issue with flexbox padding
# Хорошо — ясно, зачем изменения, какую проблему решали
 
 
b1d5272e placeholder
# Плохо — это что? О чём?
 
b1d5272e add missing placeholder to search input in header
# Хорошо — ясно, что поправили и зачем
 
 
4f5ed66 bump paperclip
# Плохо — зачем обновляли? На что повлияло?
 
4f5ed66 update paperclip: adds support for stream downloads for S3 objects
# Хорошо — paperclip обновили ради быстрого скачивания из S3

Отсюда правило: не что изменили, а что и зачем. Помимо этого правила я советую придерживаться ещё одного: писать на английском в повелительном наклонении.

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

Повелительное наклонение я советую потому, что рассматриваю историю Гита, как последовательность команд‑приказов, переводящих репозиторий из одного состояния в другое:

51537554 mention Ubuntu installation instructions in README

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

Ещё по теме

P. S. Это был совет о веб‑разработке. Хотите знать всё о коде, тестах, фронтенд‑разработке, цеэсэсе, яваскрипте, рельсах и джейде? Присылайте вопросы.

Веб‑разработка
Отправить
Поделиться
Запинить

Рекомендуем другие советы