ТЫ!
Да, ты! Мне нужно тебе кое-что сказать!
Ваши сообщения о коммитах отстой!
Откуда я знаю? Ну, если вы читаете эту статью, значит, вас сюда прислал один из ваших коллег!
И угадайте, что! Ваш коллега прав!
Не пытайтесь спорить! Я все равно не верю твоему мнению! Как я мог доверять разработчику, чьи сообщения о коммитах отстой?!
И даже не думайте жаловаться своему начальнику на интеллектуальные домогательства! Ваш коллега хочет только помочь вам стать лучше!
Но прежде чем вам помогут, вы должны признать, что у вас есть проблема!
Так что повторяйте за мной:
Мои сообщения коммита отстой
Хорошо.
Теперь давайте посмотрим, что мы можем сделать, чтобы вы стали лучшим разработчиком и, как следствие, лучшей личностью.
Шаг 1: понять, что не так
Я рискну и предположу, что последней каплей в ведро жидкого терпения вашего коллеги было сообщение коммита, несколько похожее на это:
Исправить ошибки
Измененный алгоритм
Реализовать функцию
Чувство вины?
Сообщения фиксации должны быть краткими описаниями того, что конкретно изменилось в содержимом вашей фиксации.
Вместо этого вы в общих чертах описали каждую фиксацию, когда-либо сделанную.
Отсутствие конкретики на самом деле довольно поразительно. Вы ничего не добились.
Это похоже на отчет о книге, состоящий только из «прочитал несколько страниц».
Возможно, вы сделали что-то немного лучше, что-то вроде этого:
Фиксированный PR по отзывам
По крайней мере, здесь есть намек на контекст, указывающий мне на один из ваших предыдущих коммитов, но я до сих пор понятия не имею, каким может быть содержание вашего коммита.
Конечно, это что-то.
Но это все еще не очень хорошо.
Хочешь узнать больше?
Шаг 2: Понимание цели сообщения фиксации
Когда кодовые базы существуют в течение более длительного периода времени и ответственность переходит из рук в руки многих нетерпеливых разработчиков, каждый из которых запечатлевает частичку себя в кодовой базе, сами кодовые базы со временем, естественно, эволюционируют.
Старшие инженеры часто уходят от стека после долгой работы с ним только для того, чтобы увидеть его полностью искаженным к тому времени, когда они возвращаются после временного пребывания в другом проекте. Прекрасные абстрактные классы, созданные ими как надежная гарантия максимально возможного качества кода, превратились в постапокалиптическое кошмарное топливо самого худшего вида. Гнилой спагетти-код, расщепляющийся на сотни строк логики try-catch, которую можно было решить с помощью одного или двух абстрактных типов.
Внезапно обнаруживается фатальная ошибка, которая спрятана где-то в глубокой бездне ужасного кода.
Именно в этот момент становятся важными высококачественные сообщения коммитов.
Хороший разработчик может начать либо просматривать журнал коммитов, либо начать искать изменения в коде, ссылаясь на соответствующие коммиты, и начать выводить свой способ обнаружения изменения, которое привело к ошибке, которая теперь угрожает самому существованию рассматриваемого приложения.
Представьте себе обратную ситуацию с офисным пространством, когда алгоритм округляет все исходящие выплаты.
Наш самаритянин разработчик просматривает кодовую базу и натыкается на следующее:
TRT-402-feature-customer-payment исправить платежи с нулевой стоимостью, округлив до 1
Разработчик видит сообщение и немедленно анализирует код, выявляя ошибку и исправляя ее в течение нескольких минут.
Всей нашей команде разработчиков удается сохранить свои рабочие места. Инженер может вернуться домой, чувствуя себя суперзвездой. Дочь инженера может еще заниматься карате, сын еще учиться в колледже. Даже их кошке разрешено немного кошачьей мяты. Все благодаря хорошему разработчику, который нашел время, чтобы написать достойное сообщение о коммите!
Теперь предположим, что ВЫ написали сообщение фиксации. Я просто предполагаю, что это будет что-то вроде того, что вынаписали бы:
исправить ошибку, лол, спасибо, пока, weekend4ever xD
Излишне говорить, что вы разорили компанию, а ваши коллеги остались без работы.
Все потому, что ваши сообщения о коммитах – отстой.
Шаг 3: Как улучшить
Так что же делает сообщение о коммите хорошим?
Обычно, если вы можете передать три части информации, вы готовы к работе:
ЧТО сделано?
ПОЧЕМУ это было сделано?
КАК это было сделано?
Если вы каким-либо образом можете ответить на все три сообщения, то вы абсолютно золоты. Но я признаю, что удовлетворить все три требования может быть немного сложно, особенно если учесть, что сообщения коммитов должны быть относительно короткими.
Особенно понимание контекста изменения будет довольно сложным для будущих читателей. Сопровождающие, работающие над одним и тем же стеком через 2 года, не будут иметь представления о проблемах, с которыми столкнулась ваша команда; с их точки зрения, это давно решенные проблемы, они не стали бы тратить время на изучение древних, казалось бы, искорененных ошибок (и они были бы правы, думая так, при наличии надлежащей документации).
Не отчаивайтесь!
Дать контекст на самом деле довольно просто! Ссылайтесь на код задачи/тикета, над которым вы работаете, и будущим разработчикам нужно только найти его в любом инструменте управления задачами, который вы используете! Предполагая, что задача четко определена, это должно дать много контекста в ретроспективе.
Следующий шаг — убедиться, что вы точно написали, какую часть логики вы изменяете в своем коде. Иногда может быть непросто проследить, как изменение А приводит к изменению Б, чтобы облегчить изменение С, но в этом случае не бойтесь использовать такие предложения, как «[изменить А], чтобы позволить [изменить Б]» в рамках сообщение фиксации.
Хотя сообщения о коммите, как правило, должны быть короткими и точными, чем больше контекста вы можете дать, тем лучше.
При указании фактического изменения логики не бойтесь использовать имена функций или переменных, которые вы изменяете. Они могут не существовать под теми же именами в будущих итерациях, но это все равно дает читателю что-то, за что можно ухватиться, пытаясь понять, что было сделано.
Наконец, постарайтесь точно сформулировать ожидаемое поведение, если оно не очевидно сразу. Если вы отфильтровываете определенные элементы, которые не следует включать в дальнейшую обработку из-за ошибки пользовательского интерфейса, связанной с этими элементами, напишите об этом в сообщении. Нет проблем написать «чтобы [компонент X] не рисовал повторяющиеся значения» или подобные предложения, четко указывая цель изменения.
Без желаемого результата разработчики могут видеть сообщение, точно понимать, что вы делаете и как вы это делаете, но быть совершенно не в состоянии понять, как это каким-либо образом повлияет на ваш продукт.
Немотивированный код, каким бы логичным он ни был, сбивает с толку.
Отсутствие намерения может привести к повторному появлению ошибок, когда разработчик пытается изменить логику, которую трудно понять.
Вывод
Вы дочитали до конца! С такой самоотверженностью я могу только предположить, что ваши сообщения о коммитах будут превосходными в будущем!
Я могу только надеяться, что, возможно, однажды мы вместе поработаем над проектом, и я посмотрю на ваши сообщения о коммитах и скажу: «Вау, я понял!»
Так что продолжайте свой путь и покажите своему коллеге, насколько вы стали лучше! И когда придет время, когда вы прочитаете ужасающие сообщения о коммите, которые кто-то напоминает вам о себе в прошлом 10 минут назад, не сомневайтесь!
Позвольте мне сказать им, что они делают неправильно!
