По хардкору: что писать в комментарии к коммиту

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

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

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

На каком языке писать

В коде вы работаете с Post, Blog, User. Вы мыслите ими и не задумываясь используете в речи: добавим юзеру аватарку, покажем популярные посты в блоге.

Комментарии на русском сбивают с толку и заставляют вспоминать, что это и где:

f0b4ac поправил верстку подвала статьи

«Статья». Это у нас что? Article, Post, BlogEntry? Если коммит на английском, проблем нет:

f0b4ac fix post footer markup

Пишите на английском

Что писать в комментарии

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

Полезный комментарий описывает не что было сделано, а результат в мире ~~клиента~~ разработчика:

# Плохо: это мы и в диффе видим.
# Зачем добавляли-то? Что пытались поправить?
d77d9f add <div> wrap

# Хорошо: ясно, зачем сделаны изменения, какую проблему решали
d77d9f fix Firefox issue with flexbox padding

Не что сделано, а зачем

В каком времени

Я рассматриваю историю Гита как историю команд, приказов, приводящих репозиторий из одного состояния в другое. Поэтому пишу в повелительном наклонении. Чтобы было проще писать, использую шаблон-скороговорку:

# If applied, this commit will
mention Ubuntu installation instructions in README

В повелительном наклонении

ПРОТИП: если в комментарии есть and, скорее всего, в коммите несколько несвязанных изменений:

fix ... and update ...
introduce ... and correct ...

Дополнительное чтение

P. S. Ещё больше постов о программировании, тестах и культуре разработки у меня в Телеграме.