Изменения в коммите (дифф) рассказывают, что изменилось. Единственный способ объяснить, зачем эти изменения и какая от них польза — комментарий к коммиту. Полезный комментарий описывает не изменения в коде, а их результат в мире разработчика:
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. Это был совет о веб‑разработке. Хотите знать всё о коде, тестах, фронтенд‑разработке, цеэсэсе, яваскрипте, рельсах и джейде? Присылайте вопросы.