Давайте поговорим о том, как писать правильные сообщения к коммитам. Так сложилось, что писать их приходится всем, но не все делают это правильно: иногда кажется, что какая-то дополнительная работа, которую не обязательно делать хорошо. А во время ревью кода до сообщений редко доходит очередь: есть, что ещё обсудить. Вы наверняка делали коммиты с сообщением «small fixes», да? :)
Но при этом часто бывают ситуации, когда правильные сообщения у коммита резко упрощают жизнь: надо посмотреть, кто, когда и зачем менял что-то в конкретном модуле или почему вот тут стоит такой странный условный оператор. Если у коммита с добавлением этого кода будет сообщение «add weird if», это вряд ли поможет, а вот, например «add nds calclulation for germany» даст куда больше информации.
Давайте соберём чеклист хорошего сообщения к коммиту:
1. На английском. У нас ведь код проекта на английском. Странно переводить его на русский, чтобы читающий потом перевёл его на английский. Если комментарий на русском, получается такой излишне длинный путь: сначала автору кода надо перевести свой код («class Payment: …») на русский («класс платежа»), чтобы потом читающий коммит совершил обратный перевод: «а, класс платежа — это, наверное, Payment». Если писать сразу на английском, этого можно избежать.
2. С дополнительной информацией. Сообщение «add Payment class» выглядит странно: любой может увидеть, что добавлен класс Payment по содержанию коммита, незачем писать об этом в сообщении. Зато можно написать, зачем были внесены изменения: «refactor intergration with Yandex.Kassa». Так сообщения будут нести больше пользы: по логу можно будет понять, какие именно проблемы решались, а не просто увидеть тот же список изменений, что и в diff.
3. Не длинный. Одна строка, не больше твита (старого, в 140 символов). Сообщения стоит делать лаконичными, чтобы в них была сформулирована самая суть изменений без лишней информации.
#deeppostpythonfs
Но при этом часто бывают ситуации, когда правильные сообщения у коммита резко упрощают жизнь: надо посмотреть, кто, когда и зачем менял что-то в конкретном модуле или почему вот тут стоит такой странный условный оператор. Если у коммита с добавлением этого кода будет сообщение «add weird if», это вряд ли поможет, а вот, например «add nds calclulation for germany» даст куда больше информации.
Давайте соберём чеклист хорошего сообщения к коммиту:
1. На английском. У нас ведь код проекта на английском. Странно переводить его на русский, чтобы читающий потом перевёл его на английский. Если комментарий на русском, получается такой излишне длинный путь: сначала автору кода надо перевести свой код («class Payment: …») на русский («класс платежа»), чтобы потом читающий коммит совершил обратный перевод: «а, класс платежа — это, наверное, Payment». Если писать сразу на английском, этого можно избежать.
2. С дополнительной информацией. Сообщение «add Payment class» выглядит странно: любой может увидеть, что добавлен класс Payment по содержанию коммита, незачем писать об этом в сообщении. Зато можно написать, зачем были внесены изменения: «refactor intergration with Yandex.Kassa». Так сообщения будут нести больше пользы: по логу можно будет понять, какие именно проблемы решались, а не просто увидеть тот же список изменений, что и в diff.
3. Не длинный. Одна строка, не больше твита (старого, в 140 символов). Сообщения стоит делать лаконичными, чтобы в них была сформулирована самая суть изменений без лишней информации.
#deeppostpythonfs