Взгляд на окончательный коммит
10 января 2024 г.Разработчики по всему миру вносят изменения каждый день. Означает ли это, что эта небольшая часть каждого процесса разработки может иметь большое влияние? Можем ли мы, приложив разумные усилия, получить более чистую историю, автоматическое управление версиями артефактов и упрощенные проверки кода сложных функций?
В этой статье я раскрою принципы, лежащие в основе The Ultimate Commit, которые помогут вам улучшить процесс разработки и значительно снизить сложность совместной разработки.
Существуют разные системы контроля версий, но я хотел бы подчеркнуть, что эти мысли основаны на моем опыте работы с системами на основе git и не проверены на других системах контроля версий.
Мотивация
Рационально говоря, нам должно быть объективно выгодно, если мы приложим некоторые усилия, чтобы сделать что-то «лучше». Если мы улучшим наш подход к принятию обязательств, мы должны использовать эти результаты. В противном случае это не имеет смысла. Какой полезности мы можем достичь?
Упрощенное понимание программы
Понимание программы занимает не менее половины рабочего времени. Станут ли разработчики счастливее и продуктивнее, если проверки кода будут проходить быстрее и плавнее? Как часто вы встречали какой-нибудь код, работающий более 6 месяцев, и не могли вспомнить причину этого?
Мы могли бы заменить огромные усилия при проверке и понимании кода в целом относительно небольшими усилиями по каждому изменению. В конце концов, инженеры не страдают от этой рутинной деятельности и сохраняют мотивацию.
Более практичный анализ кода
В некоторых известных исследовательских работах говорится, что после 200-400 LOC плотность обнаружения ошибок резко снижается. В то же время удержать характеристики в таких жестких пределах невозможно. Должно быть что-то более атомарное. Случайно проверенные файлы без ограниченной области действия, смешанный рефакторинг и код функций могут сделать вашу проверку кода бесполезной.
Более структурированный подход делает рецензента более внимательным, что помогает обнаружить больше проблем на ранней стадии и в целом экономит время команды.
Анализ истории изменений
Код должен быть самодокументирован, иметь понятные имена переменных, объясняющие, что находится внутри, и точные имена методов, которые не заставляют вас заглядывать внутрь, поскольку это очевидно из имени метода.
По-прежнему имеет смысл писать комментарии к неочевидным исправлениям, которые не следует периодически откатывать, например, явно переопределить версию транзитивной зависимости.
Но иногда мы не понимаем, почему какой-то код был написан именно так, а не альтернативно, открываем историю и видим… ничего.
Единственное «исправление проверки кода» или сжатое название заявки «XX-1234 Моя удивительная функция». История на самом деле не помогает разработчикам поддерживать существующий код, и это можно улучшить.
Ultimate Commit должен предоставить вам больше контекста для каждого конкретного изменения, упростить долгосрочную работу, помочь вам вернуться позже и внести некоторые изменения с минимальными побочными эффектами в виде пропущенных фрагментов памяти.
Предполагаемое управление версиями & Примечания к изменениям
Смысл каждого изменения важен; это последовательный журнал изменений кода, который поможет вам автоматизировать управление версиями. Поскольку набор коммитов — это набор изменений, мы можем использовать его.
Я не называю это «Примечаниями к выпуску», а скорее «Примечаниями к изменениям», потому что разработчики помогают себе, а не конечным пользователям, когда пишут сообщения о фиксации. Аудитория, которая получит наибольшую прибыль от чтения заметок, полученных из коммитов.
Мы выяснили, что можно улучшить с помощью «Ultimate Commit», поэтому давайте попробуем сделать очевидными его свойства.
Критические свойства окончательного коммита
Маленький
Учитывать сложные структуры во время проверки кода и анализа истории непросто. Небольшие ограниченные изменения гораздо проще понять. Представьте себе, что вы просматриваете результаты рефакторинга и бизнес-код отдельно.
В конце концов, это один и тот же код, но части обзора логически разделены.
Вы можете быстро просмотреть рефакторинги или более 100 файлов изменений стиля и тщательно просмотреть деловые изменения, которые повлияют на вашу способность как рецензента сосредоточиться на важных вещах и сохранить высокую плотность обнаружения ошибок.
Читабельно
В настоящее время это очевидно, но я должен отметить, что читаемость сообщений о коммитах напрямую влияет на анализ истории и понимание программы.
Если вы сэкономите 1 минуту вместо того, чтобы правильно сформулировать сообщение о коммите сегодня, это будет преследовать вас на протяжении всей жизни проекта, пока вы не покинете компанию.
Выразительность
Я часто видел коммиты с таким описанием, как «исправить комментарии к проверке кода», иногда даже повторяющимся много раз. Эти коммиты имеют бессмысленное описание, поскольку не объясняют, почему (даже какие) изменения были внесены. Вы можете мне возразить: но изменения были внесены потому, что рецензент кода добавил комментарий. Это одна из самых популярных ошибок, которые я видел.
Проверка кода — это инструмент обратной связи, а не причина. Основная задача, которую вы решаете на код-ревью, — это направление внимания на те или иные проблемы. Выделяйте проблемы на раннем этапе, чтобы устранить их до того, как будет выявлена основная причина.
Выразительные сообщения о коммитах помогут вам сформулировать и проверить, правильно ли вы понимаете мотивацию комментария к обзору. Это просто проблема стиля или ошибка производительности?
Нормализация
Не нужно дублировать информацию. Краткое изложение Ultimate Commit должно дать вам больше информации, чем вы можете прочитать из его кода. Например, «добавить оператор if» повторяет содержимое, а «обработать крайний случай» объясняет, почему необходимы эти изменения.
Структурировано
Может быть несколько типов логических изменений, поэтому, если мы определим таксономию, мы сможем автоматизировать семантическое управление версиями, например:
Завершено
Эффективное принятие решений не коррелирует со временем; нет смысла коммитить каждый час или к концу дня. В то же время, если изменение занимает больше времени, чем ваша сессия разработки, или состоит из нескольких изменений, вы, вероятно, можете его разложить. Например, «внедрить REST API со скрытыми заглушками» и «повысить устойчивость за счет повторных попыток сетевых вызовов».
Единый
Может быть неэффективно сканировать одни изменения глазами, сформулированными в пассивном залоге, а другие – в активном. У некоторых есть информация об исходной ветке/задаче, у других нет, или эта информация добавляется по-другому.
Для каждого конкретного коммита должен быть один стандарт.
Маленький, читаемый, выразительный, нормализованный, структурированный, завершенный и унифицированный. УХ ТЫ! Множество свойств, которые нужно реализовать, некоторые из них полностью лежат на плечах разработчика, а другими можно управлять независимо.
Практики
Давайте посмотрим, какие методы могут помочь нам удовлетворить указанные выше свойства.
Обычные фиксации
Я надеюсь, что некоторые из вас (которые уже знакомы с обычными коммитами) понимают, что эта спецификация охватывает большую часть свойств Ultimate Commit. Для других позвольте мне объяснить что это такое.
По данным сайта:
<блок-цитата>Спецификация обычных коммитов представляет собой упрощенное соглашение, лежащее в основе сообщений о фиксации. Он предоставляет простой набор правил для создания явной истории коммитов; что упрощает написание автоматизированных инструментов поверх него. Это соглашение соответствует SemVer, описывая функции, исправления и критические изменения, внесенные в сообщения о фиксации.
Если команда следует соглашению, их коммиты получают следующие свойства Ultimate Commit: небольшой (атомарный), структурированный, завершенный и частично унифицированный.
Обычные коммиты предлагают множество стандартных типов коммитов, таких как исправление, исправление, рутина, рефакторинг, документация, стиль, тестирование, производительность (производительность), ci, сборка и возврат. Я настоятельно рекомендую вам прочитать больше об этой практике на их сайте.
Активный голос
Обычно возникает естественное намерение написать сводку коммита в пассивном залоге, например: «был введен пользовательский API». Проблема с этим подходом заключается в том, что пассивный залог сложнее читать, поскольку глаголы могут радикально изменить свою инфинитивную форму; в противном случае форма инфинитива в настоящем времени упрощает задачу.
Другая мотивация заключается в том, что сообщения о коммитах будут унифицированы с коммитами Merge, которые начинаются с «Merge…»
Эта практика помогает унифицировать и улучшить читаемость коммитов.
Хватит раздавливать
Если вы начинаете с обычных коммитов, вам следует перестать их раздавливать. Теперь ваша история наполнена актуальной информацией, которую вы можете использовать позже, не потеряйте ее.
Коммиты в истории становятся читабельными и выразительными. Они небольшие, унифицированные и структурированные, поэтому вы можете легко понять, почему были внесены те или иные изменения.
Имя ветки представляет собой код заявки и размещается в нижнем колонтитуле сообщения о фиксации
Определение филиалов по коду билета упрощает задачу. Во-первых, вам вообще не нужно думать о названии ветки. Во-вторых, вы можете добавить имя ветки в нижний колонтитул обычного коммита, и если позже вы захотите найти все коммиты, связанные с билетом XYZ-1234, вы просто выполните поиск по этому коду в истории git. Если бы филиал назывался по билету, вы бы сэкономили много времени.
Очевидно, что если вы хотите иметь исключения из этого правила, иногда вы можете это сделать, но имейте в виду, что это нарушает отслеживаемость вашей разработки.
Что лучше? Добавление имени ветки легко автоматизировать, но внесение изменений может оказаться непростым делом. Итак, нажмите «звездочку» на этой сути, чтобы не потерять расширенный git-хук для добавления ветки к сообщению о фиксации. .
«Почему» вместо «Что»
В вашем коммит-диффе уже указано, что было изменено. Вы можете добавить дополнительную информацию в сообщение о фиксации, чтобы объяснить «почему». Используйте историю коммитов как чат для общения с новыми разработчиками (или с самим собой через год), которые не понимают, почему была добавлена та или иная строка, чтобы они ее прочитали и не беспокоили вас повторно. Выше я привел несколько примеров.
Инструменты
Создание
Плагины IDE и инструменты командной строки могут помочь вам структурировать сообщения в соответствии со спецификациями.
Git Hooks может добавлять имя ветки в конец каждого коммита. Существует несколько способов реализации перехватчиков git: от ручного обновления конфигурации git до использования системных плагинов (пример для gradle , пример для специалистов по интерфейсу).
Проверка
Плагины IDE также могут помочь вам проверить сообщения о фиксации.
Git Hooks может помочь проверить сообщения коммитов на соответствие спецификациям и другим требованиям.
Серверные хуки Git помогают защититься от периодических нарушений правил.
Генерация версии
Semantic Release — отличный инструмент для вычисления следующей семантической версии вашего артефакта и публикации ее на сервере git. Commitizen также популярен.
Большинство традиционных инструментов на основе коммитов упоминаются здесь.
Заключение
Окончательные коммиты не идеальны, поскольку требуют некоторых усилий, но со временем вы улучшаете свой код-ревью, понимание кода и, не побоюсь сказать, культуру вашей разработки. Обсудите методы внутри своей команды и выберите лучшие для вашего случая.
Оригинал