Зачем нужны комментарии к коммитам?

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

В предыдущем посте мы обсудили почему нужно придерживаться внутренних распорядков компании (tl;dr: потому что иначе вы станете проблемой и от вас избавятся), но мотивация делать это чисто KPI-ная—если вас оценивают по показателю "двигание тасочек", то логично этот показатель держать на высоком уровне.

А что, если в компании нет регламента? Должна ли быть у инженера мотивация писать грамотные комментарии к коммитам и работать с системами управления проектами?

Ярчайший пример такой ситуации это клиенты Телеграма: в андроид клиенте вы не увидите ни одного комментария к коммиту. Раньше это были просто "fixes", сейчас более приличное "Update to X.X.X". Автор приложения оставил комментарий что он не хочет тратить время на комменты, бранчи, тэги и прочий мусор: «I don't want to waste time to writing tags, commit comments, etc.» Коммент был сделан 7 лет назад и тогда он оправдывался что не ждал что код опубликуют на гитхабе, но ситуация не изменилась.

macOS клиент тоже не радует понятными дескрипшенами. Лаконичное "fixes" впрочем иногда сменяется редкими "video calls" или "audio player".

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

Главное помнить: correlation ≠ causation. То, что разработчик телеграма не пишет комментов, не значит что благодаря этому телеграм-клиент хороший. Если вы перестанете писать комменты, то это не значит что ваш софт станет лучше. Скорее наоборот.

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

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

Ладно описания, но зачем нужны номера тикетов в истории коммитов? Во многих случаях ваш софт выдаётся на несколько разных окружений. Допустим у вас есть тикет, как понять, он сделан в версии X? Если вы не зафиксировали номер тикета в комменте, то это отдаётся на откуп программисту, типа написать в в тикете "исправил в версии X.X.X" и это можно забыть (а потом к вам лично придёт QA), а вот если указать номер тикета в коммите, то он автоматически подтянется и по истории сразу будет понятно что и куда попало.

Часто у меня бывает ситуация когда я нахожу проблему в опенсорсной библиотеке и попадаю на багтрекер. Если проблема уже исправлена то там с очень высокой вероятностью будет указана версия где это поправлено, или через коммит, или через коммит+еще комментарий в тикете. Если бы вместо истории я видел "fixes" то мне оставалось бы только обновляться на последнюю версию в надежде что ничего не сломается.

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

Поэтому я пишу историю даже на пет-проектах которые никому не показываю, и вам советую делать то же.

P.S.: остальные телеграм клиенты ведут ±нормальную историю, хотя там тоже почти везде 1 разработчик.


Понравился материал? Подписывайся на мой телеграм канал: https://t.me/full_of_hatred