В августе этого года была опубликована статья под названием My favourite Git commit, затем не так давно переведена на русский, было много обсуждений на reddit, hacker news. Если вкртаце, сообщение к тому самому коммиту из статьи содержит достаточно много деталей, объяснений проблемы и решения, даже посопереживать там есть чему - именно это, по мнению автора, является свойствами хорошего коммита. И я, как следует из заголовка, не согласен с этим.

Image by Paul Brennan from Pixabay

Немного деталей

Сам коммит. Изменения были в файле под названием modules/router/templates/routes.conf.erb. Если сейчас взглянуть в ту дирректорию, то там уже нет этого файла. В сообщении к коммиту описаны причины, способ обнаружения, способ исправления и жалоба о потраченном времени, которого не вернуть. Конкретно в этом коммите исправлялась кодировка одного символа, мешаюшая выполнению скриптов в проекте. Важная деталь: изменения коснулись в этом коммите лишь одного символа. На текущий момент в проекте уже больше 27’000 коммитов.

Сообщения к коммиту не помогают искать проблемы и их причины

Мне показали такой скрипт рабочего процесса программиста:

  • Взять баг в Jira в работу
  • Найти строчку, код в которой работает с ошибкой
  • Найти коммит, в котором эта строчка была обновлена
  • В сообщении к комиту найти ссылку на задачу в Jira, в рамках которой было сделано это обновление
  • Найти по задаче в Jira пул-реквест, в рамках которого было сделано это обновление
  • Полученная информация расширит ваш кругозор в рамках решения вашей изначальной задачи

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

Если перенести содержимое одного файла в другой, то его история станет труднодоступной

Вернувшись к коммиту Dan Carley, можно понять, что если какой-то будущий участник проекта столкнется с такой же ошибкой, что и Den, то коммит Den-а не поможет, так как

  • файла с этим коммитом уже нет
  • изменение было сделано где-то на 463 строчке конфигурационного файла в одном символе пробела

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

Git bisect | Git log –grep

Вот это мое “любимое”. Распространенное утверждение, что git bisect может помочь найти этот коммит. Да, git bisect может найти коммит, в котором в первые появилась проблема, но он не поможет в том случае, если проблема появилась вот только что. git bisect не подскажет вам, что проблема уже была 6 лет назад, и в тот раз заботливый программист описал что делать и как.

git log мощный инструмент, с его помощью можно найти коммит по сообщению. Но задайте себе вопрос: вы будете запускать поиск по git коммитам если у вас в проекте будет возникать ошибка кодировки при выполнении скриптов? Да нет же. Большая часть ответит, что они откроют google, или сразу SO и там будут искать решение проблемы. В данном случае никакой git log не поможет, потому что это не тот инструмент, который используют для поиска решений по проблеме. Хотя я нисколько не сомневаюсь, что автор коммита умный парень, и собрал верную информацию для нахождения проблемы с кодировками.

Как можно было поступить

Тест

Самое первое, что пришло мне в голову - это тест. Написать тест, который будет контролировать появление новых подобных ошибок в проекте (Den-у следовало написать тест на bash, который бы проверял кодировку в файлах проекта перед запуском всех тестов). При настроенном CI - это мощнейший инструмент для будущих участников проекта. Если бы кто-либо в будущем написал один/несколько (да хоть весь файл) в другой кодировке, то его остановил бы тест, который бы любезно сообщал о принятой кодировке в проекте - шах и мат.

Документация

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

Длинные сообщения к коммитам - зло для проекта

Сообщение в коммите к изменению одного символа является труднодоступной информацией. Проект когда-то заплатил за эту информацию, но теперь она не стоит ничего, поскольку бесполезно барахтается в море из 27’000 коммитов. И проекту придется платить еще, если подобная проблема выстрелит в будущем.

Длинные сообщения в коммитах ухудшают поддерживаемость

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