Культура commit-ов

статья

Created: 04 Dec 2020 Updated: 05 Dec 2020


С самого начал работы с системами контроля версий, будь то SVN, Mercurial или Git, я задал себе вопрос:

“Как правильно, а главное качественно писать комментарий к своему изменению кода?”

И казалось бы, что может быть проще ответа: “Что сделал, то и Опиши”.

Но на практике всё оказалось немного сложнее.

Ошибки

Когда проект молодой, и первый, а возможно и последующие, его этапы разработки идут под лозунгом:

Сроки горят

мало кто задумывается о такой мелочи как текст, который оставляют причастные к коду люди в системе контроля версий.

В конечном итоге история проекта принимает вид “мусорки”, в которую кладут “отходы” без разделения.

“И что в этом плохого?” - сразу возникнет вопрос. Если посмотреть поверхностно - ничего.

Проекту, от того, что фигурирует в истории к коду - всё равно, он и так собирается и выполняет свои бизнес задачи.

Проходит время. Проект растёт. Количество и виды комментариев увеличиваются, мелькают строки со смайликами, номерами задач, невразумительными fix, reviw, упражнения в английском и т.д.

Работники всё чаще и чаще начинают сталкиваться с необходимостью смотреть историю, чтоб понять кто изменил тот или иной участок кода и в рамках какой задачи.

И каково же бывает удивление, когда находиться нужный commit из 15-и файлов с комментарием fix2 от человека, который уже не работает на проекте.

Выход есть

И он заключается в следовании простым правилам с начала проекта или с момента, когда всем в команде стало понятно, что так дальше нельзя.

  • Обсудить и зафиксировать язык комментариев

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

  • Начать придерживаться конвенции

    Это не только стандартизирует ваши сообщения, но и сделает их удобными для автоматической обработки.

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

    В changelog-builder/blob/master/CHANGELOG.md можно увидеть пример того, как выглядит автоматически формируемый файл.

    Кстати, проект changelog-builder предназначен для формирования CHANGELOG.md файла и Вы можете им воспользоваться. Неважно, придерживаетесь ли Вы конвенции или нет, файл сформируется, но вот насколько он будет удобочитаем и понятен - это Вы и проверите.

    Так же для IntelliJ IDEA я немного усовершенствовал плагин, который позволяет легко набирать комментарии согласно конвенции.

  • Использовать squash

    Когда в удалённый репозиторий отправляется две одинаковых строки комментария - это повод задуматься.

    “А одинаковые ли причины несут эти изменения?”, - и в 100% случаях ответ - НЕТ.

  • Использовать push –force

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

  • Не писать “что сделали”, писать “что сделано”

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

    До

    откорректировал регулярное выражение, так как не обрабатывались некоторые случаи

    После

    откорректировано регулярное выражение, так как случай рамма не обрабатывался

    Для своих проектов я написал и начал использовать git-hook commit-msg, который проверяет обязательное наличие в комментариях хотя бы одного слова из списка.

Заключение

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

А как в вашей команде обстоят дела с историей commit-ов?

Успехов!