Какой смысл писать комментарий к коммиту?

Question

[Алексей Юдов]

Перед тем как читать вопрос ознакомься с этой статьей или её переводом, чтобы понять о чем речь.

Недавно с коллегами перешли на трекер, для организации работы. Соответственно возник вопрос "как связать задачи в трекере с изменениями в репозитории? Как оформлять ветки и коммиты?"
По ходу обсуждения решили что есть смысл именовать ветки по коду задачи из трекера, например, PRJ-3 и аналогично коммиты PRJ-3. Возникло предложение писать коммиты в таком формате PRJ-3 <краткий коммент к коммиту>, но не увидели в комментах к коммиту смысла (коммент ради коммента).

Как вы считаете, когда есть смысл писать коммент к коммиту и есть ли он вообще?

Comments

[longclaps]

Перед тем как читать вопрос ознакомься с этой статьей или её переводом, чтобы понять о чем речь.

Жлоба видно за версту.

[Ерлан Ибраев]

А какая проблема связать коммит с задачей?
В IDEA есть Task&Context. Где можно настроить связь с системой управления проектом.
Например такими как redmin и jira.
Когда берете задачу в работу, то выполняете "Open task", а там либо создаете новую ветку, либо используете существующую. Ну и когда коммитите в IDEA, то коммит называется по названию задачи.
Там есть ещё немного удобств. Например при переключении между тасками открываются файлы, которые были ранее открыты в таске.

[Макс]

На этот вопрос нет объективного ответа. Обычно сам пишу как вы привели пример: `PRJ-77 Implement whatever`. Но если задача попадается забористая или есть какие-то технические моменты которые не отразить в комментах к коду и этим уточнениям нечего делать в трекере задач, то это тот редкий случай когда пишу комментарий к коммиту.

Answer 1

[DevMan]

осмысленное описание комита - маст хэв.
prj-3 - это говно, а не описание комита.

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

Comments

[Алексей Юдов]

DevMan ,

Почему маст хэв и для кого? Можно ведь по ИД/Коду задачи провалиться или перейти по ссылке в трекер и понять контекст задачи, следователно понять зачем нужен коммит. В чем преимущество писать <краткий коммент к коммиту>?

[rPman]

TCloud, если у вас по верх консольного интерфейса git накручен какой то gui, который связывает его с тасками, то пожалуйста, делайте идентификаторы в коммитах

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

[Алексей Юдов]

rPman,

зачем? Другие люди же могут открыть трекер, зайти в таску и посмотреть зачем коммит нужен

[rPman]

TCloud, перед тобой 100500 записей в changelog гит, тупо идентификаторы, ты должен каждый перепроверить глазами в трекере?

человек не должен работать в голове с техническими идентификаторами, это мучение... да запомнить можно все, но зачем создавать геморой себе и будущим разработчикам на пустом месте?

[Алексей Юдов]

rPman,

не понял о чем речь. Что перепроверять, информативность коммитов? Или если речь о ревью, то на ревью проверяются не коммиты

[DevMan]

TCloud, решение задачи может (и должно) иметь множество комитов.
если конечно это не "заменить А на Б".

[Алексей Юдов]

Лентюй,
Я не смогу знать "что хотел родить автор" изходя из Кода/Ид задачи из трекера?

[DevMan]

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

на решение задачи я могу сделать несколько десятков или сотен комитов.
как в них разобраться читая только бессмысленное prj-3.

[DevMan]

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

но гит (как и любая другая vcs) придуман немножко для другого.

[Алексей Юдов]

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

[DevMan]

TCloud, затем, что если что-то пошло не так, просто найти где именно.

[Алексей Юдов]

Лентюй,
комментарии к коммиту должны быть информативные, если они информативные, значит они осмысленные. Как они могут быть осмысленными если сам смысл комментария к коммиту не понятен? Максимум что можно добавить, в моем случае (см вопрос), это Код/Ид задачи.

[Алексей Юдов]

DevMan,
каким образом отладка начала через гит производится? Как что-то что может пойти не так было смерджено в релиз?

[DevMan]

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

[DevMan]

TCloud, и никто ничего никому не должен. вам нравиться видеть в логе только номера тасок? да гавно вопрос – пользуйтесь на здоровье.

[DevMan]

TCloud,

Как что-то что может пойти не так было смерджено в релиз?

а гит у вас только для релиза?
в деве не участвует?

[Алексей Юдов]

DevMan,
то что должно уйти в дев сначало тестируется. И вопрос задевает только комментарий к коммиту

PRJ-3 <краткий коммент к коммиту>

[Алексей Юдов]

DevMan,
Но я ещё раз отмечу, что ответа на вопрос "зачем?" я не увидел. А для бизнеса это самый важный вопрос.
Если это не способствует более быстрому и более дешёвому достижение бизнес-целей и решению бизнес-задач, то это не нужно делать. Разработчикам платят не за написание кода, а за решение конкретных бизнес-задач. Бизнес будет счастлив, если мы не напишем ни строчки кода, но решим все бизнес-задачи.

[DevMan]

TCloud,

то что должно уйти в дев сначало тестируется.

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

[DevMan]

TCloud,

Но я ещё раз отмечу, что ответа на вопрос "зачем?" я не увидел.

наверное потому что читать не умеешь. или понимать.

А для бизнеса это самый важный вопрос.

и ответ на него дали.

[Алексей Юдов]

DevMan,
где же? Из ответов я пока увидел "Пиши, это аксиома", "Пиши, коммит будет лучше выглядеть", "Пиши, потому что не писать это говно" и все в таком духе. Где ответ то, какой смысл в комменте ради коммента?

[Алексей Юдов]

Почему недостаточно просто Кода/Ид задачи из трекера?

[DevMan]

TCloud, ты в глазки долбишься или не понимаешь написанное?
тебе же русским по серому написали: для навигации по истории.
что ещё надо написать?

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

[DevMan]

TCloud,

Почему недостаточно просто Кода/Ид задачи из трекера?

потому что на решение одной таски делается множество комитов.
сколько еще раз нужно это написать?

[Алексей Юдов]

DevMan,
В идеале на одну задачу должен быть один коммит. Куча коммитов возникает чаще всего из-за ошибок

[DevMan]

TCloud, это не в идеале, это лишь фантазии в отдельно взятой голове.

[Алексей Юдов]

DevMan,
кто этой навигацией потом будет пользоваться? мне как разработчику отдельно взятые коммиты ну очень редко нужны, ревьюеру они так 101% не нужны.

[Алексей Юдов]

DevMan,
в смысле? сквошить коммиты кто тебе запрещает? результат = одна задача - один коммит

[DevMan]

TCloud, тебе не нужны? не пользуйся.
о чем вообще спор?

ну не надо тебе, так не надо. а зачем тут "переубедите меня"? к чему это?

[Алексей Юдов]

DevMan,
стало интересно на стороне разобрать кейс, который выше описал.

Понятное дело что коммент в коммите важен и обязательно дожен быть информативен. Содержание коммита может определятся за счет тех или иных инструментов в команде, в зависимости от уровня коллег и прочего. К оформлению changelog-а это тоже относится. Один из самых важных моментов - это осмысленность, без неё принятие каких либо решений (даже "банальное" оформление коммента к коммиту) может привести ко множеству проблем, либо может быть неэффективным для бизнеса.

[DevMan]

TCloud, алилуя

[Алексей Юдов]

DevMan , Лентюй, iBird Rose, rPman, longclaps,
вот +/- норм ответ был у Макс , в комментах к вопросу

[DevMan]

TCloud, нормальных ответов было больше.
то, что они не вписались в вашу схему работы или они вам не подходят по каким-то другим причинам - не делает их плохими.

[Сергей Кузнецов]

Разработчикам платят не за написание кода, а за решение конкретных бизнес-задач.

У вас одноразовые задачи? Тогда комментарии и не нужны. И история проекта не нужна.

Но если проект серьёзный, то возникает необходимость в доработках или исправлении ошибок. И тогда уже вы сами себе скажете спасибо за аккуратную историю и понятные комментарии к ранее сделанной работе. Разработка не заканчивается на релизе, вы всё равно продолжите допиливать проект и доработки будут опираться на предыдущую историю. Баг-трекер это не очень удачное место для хранения истории. А что если завтра вы решите перейти на другую систему? Всю историю придётся забыть? Ссылки на тикеты это хорошо, но они второстепенны в коммите. Важно таки писать в сообщении коммита что он делает. Если у вас практикуется squash-merge, то тогда оформляйте красиво squash-коммиты, так как все остальные уничтожаются при squash.

Answer 2

[iBird Rose]

ну вот представь ситуацию, что ты свою задачу "PRJ-3" не смог с одного коммита сделать (а такое случается довольно часто). и вот у тебя образовалось 20 коммитов с комментом "PRJ-3". и ты там много чего переделывал и теперь опять что-то изменилось и тебе нужно посмотреть одну из первых реализаций задачи. ты помнишь, что она где-то в начальных коммитах, но не помнишь в каком. вот тебе и придется сидеть и открывать по одному эти коммиты и смотреть тот это или не тот.
а были бы комментарии нормальные - ты бы это увидел по ним и лишних движений бы не было.
p.s. а когда с момента реализации прошла неделя, месяц, год - ситуация усложняется в разы. потому что тут уже ты и сам не будешь помнить что и когда ты писал.

Comments

[Алексей Юдов]

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

не понял. для чего мне смотреть одну из первых реализаций?

p.s. а когда с момента реализации прошла неделя, месяц, год - ситуация усложняется в разы

про неделю я бы еще поверил в такой кейс, но месяц или год как-то не правдоподобно. Может есть кейс?

[iBird Rose]

не понял. для чего мне смотреть одну из первых реализаций?

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

про неделю я бы еще поверил в такой кейс, но месяц или год как-то не правдоподобно.

ну если твой проект живет месяц и умирает, то да. смысла нет. но открою секрет - у людей проекты десятилетиями поддерживаются)

[Алексей Юдов]

iBird Rose,
вот ты заходишь в репозиторий 10 летней давности... Как часто ты ищешь что-то, что было реализованно год назад?

[mkone112]

TCloud, мой репозиторий - 13 летней давности. Часто ищу комиты от 2008 года. Еще вопросы?

[Алексей Юдов]

mkone112, причем тут ваш репозитрий? Я искал ответ на свой кейс.

[mkone112]

TCloud, какой вопрос - такой ответ.

[Станислав Бушуев]

TCloud,

Как часто ты ищешь что-то, что было реализованно год назад?

При каждом изменении старого кода:
На таких проектах возникают вопросы типа "Почему это сделано? Почему это сделано так? Какие ещё изменения делались и где?". В идеальном мире на все эти вопросы отвечает документация, а в жизни приходится изучать контекст кода, чтобы при изменении не поломать неявно заданных тогда предположений, на которые 100% завязаны какие-то пользователи и процессы.
Идентификатор задачи полезен, чтобы найти задачу, посмотреть какие цели тогда ставились. Но чем старше код, тем больше шансы, что произошёл рассинхрон: сменилась, например, неоднократно система планирования/багтрекер, и привязки потерялись. Я лично видел задачи, где после конверсии у старых задач терялись ссылки и приложенные файлы, в которых были постановки задач.
А комментарии живут столько же, сколько и изменения.