Noveo

Наш блог Творите историю красиво

Творите историю красиво

Сегодня я хочу поделиться мыслями, которые вряд ли кто-то сочтёт ошибочными или бредовыми. Большинство согласится, что всё в проекте должно быть прекрасно: и код, и комментарии, и история правок. Осталось только начать дружно придерживаться очевидных рекомендаций.

image

1. Не стоит всё время колбасить в одной ветке

Даже если вы работаете на проекте в гордом одиночестве, для задач, занимающих полдня и больше, стоит выделять отдельные ветки. Это сильно помогает, когда прибегает менеджер и говорит: “Бросай текущую задачу, нам срочно нужно поменять размер шрифта на главном экране и сделать поставку”. Если разработка новой фичи шла в отдельной ветке, вы просто переключаетесь на master, вносите фикс и делаете сборку из находящегося в рабочем состоянии мастера. А в это время полуразобранный проект с кучей нереализованных заглушек спокойно лежит в фич-ветке, и история этой ветки будет свободна от неотносящихся к делу правок.

Уводя проект из состояния production-ready — убедитесь, что вы оставили ветку, где всё работает.

2. Правки должны быть атомарными

Вы реализуете фичу “добавление товаров в избранное”. Вносите новое поле в БД, делаете список с фильтром по этому полю и т.д. И тут — бам! — видите, что в базе вместо count написано räkna. Ох уж эти шведы, спасибо, что не по-китайски! Ну, раз уж мы всё равно тут что-то меняли, давайте исправим опечатку, IDE сама заменит все упоминания. Переименовали поле, ещё раз проверили новый экран избранного и сделали коммит “Implemented favorites list screen”. В конце недели менеджер просит старшего разрабочика проверить качество вашего кода, к тому же есть ощущение, что и с избранным что-то пошло не так. Товарищ изучает историю правок, находит вроде бы нужный коммит, открывает дифф, а там буквально весь проект в изменениях. Теперь не то что ошибки или качество кода посмотреть — тут бы отыскать хоть что-то относящееся к теме…

В любом случае, чем больше вы правите оформление, тем сложнее окажется мёржить изменения.

Если вы делаете изменения на две разные темы — убедитесь, что вы оформили их в два разных коммита.

3. Коммит должен иметь осмысленный комментарий

У каждого свой стиль написания комментариев, и это нормально, но есть общие принципы того, как делать надо и как делать не надо. Комментарий должен описывать внесённые изменения. Вот примеры комментариев, которые этого не делают:

  • Fix.
  • Fix for issue 227.
  • Some improvements.

И примеры комментариев, которые хорошо описывают внесённые изменения:

  • Fixed iOS 7 specific crash on details screen.
  • Fixed iOS 7 specific crash on details screen. Fixes #227.
  • Improved keyword search performance.

Кроме более полезного и читаемого сообщения, во втором случае используется формат, понятный для нашего Redmine. Такой коммит будет автоматически упомянут в тикете. Больше узнать об этой возможности можно в документации: http://www.redmine.org/projects/redmine/wiki/RedmineSettings#Referencing-issues-in-commit-messages.

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

Иногда приходится получать наполовину готовый проект, иногда наоборот — передавать кому-то следующему. И эти люди не всегда работают в соседнем кабинете, они могут оказаться коллегами-французами, американцами или румынами. Это отличный повод использовать простой, понятный и в то же время по возможности максимально грамотный английский язык. Постарайтесь не писать набор бессвязных слов и не тратьте усилия на составление сложноподчинённых предложений с необособленным причастным оборотом (что бы это ни значило). Сформулируйте суть в одном или двух простых предложениях. Если описать все изменения в таком объёме текста не удаётся — скорее всего, изменений слишком много, и их нужно разбить на несколько коммитов.

Описывайте изменения кратко и по существу.

4. Коммит должен быть подписан

На проекте с переменной активностью работают три человека. Первый болеет и работает из дома. Второй сейчас переезжает на новый мак. Третий вовсе был дурак. В иcтории мы видим примерно следующее:

* c812021 2015-03-30 | Merge branch 'master' into CustomConditions []
|
| * fdd25e6 2015-03-27 | Fixed missing text margins on the pairing screen. []
* | 89a23e2 2015-03-27 | Fixed a bug: not disconnecting explicitly after pairing is finished. [macbook]
|/
* 365af49 2015-03-26 | Fixed a bug: not making a call if number contains parentheses symbols. [~=niki=~]

В то время как на самом деле хотели бы видеть это:

* c812021 2015-03-30 | Merge branch 'master' into CustomConditions [Alexey Kim]
|
| * fdd25e6 2015-03-27 | Fixed missing text margins on the pairing screen. [Alexey Kim]
* | 89a23e2 2015-03-27 | Fixed a bug: not disconnecting explicitly after pairing is finished. [Ivan Petrov]
|/
* 365af49 2015-03-26 | Fixed a bug: not making a call if number contains parentheses symbols. [Nikita Ivanov]

В случае возникновения проблем всегда приятно знать, к кому идти за помощью. С коммитами из первого примера придётся побыть в роли Шерлока.

Сконфигурируйте свой Git клиент.

5. Не торопитесь публиковать изменения

Грязной может быть локальная история, но не удалённая. Если вы нарушили любое из перечисленных выше правил, но осознали это раньше, чем выполнили заветный git push — всё хорошо. Можно вернуться и подчистить историю, какой бы страшной и ляпистой она ни была. Но только если кроме вас никто не успел её увидеть. В противном случае, если вы уже сделали push в общедоступный репозиторий,  переписать историю можно, но коллеги вряд ли скажут спасибо. Возникает неприятная ситуация: после таких правок коммиты дочерние к отредактированным, если их кто-то успел сделать, останутся без родителей.

Например, вы забыли добавить новый файл в коммит, при этом закоммитанные отредактированные файлы его используют. Довольно типичная ситуация, которая мало того что приводит к нарушению как минимум первого правила (ломает сборку в текущей ветке, которой может оказаться что-то вроде master или release), так ещё и заставляет загадить историю бессмысленным коммитом в духе “Added missing files”. Совет, который обычно дают о написании важных писем, здесь работает не менее эффективно: напишите и отложите. Спустя некоторое время посмотрите холодным взглядом и, если написанное всё ещё выглядит разумно, — отправляйте. За прошедшее время вы вполне можете обнаружить и более серьёзный баг, который либо будет вовремя исправлен, либо заставит вынести происходящее в отдельную ветку и оставить текущую чистой и безбажной.

Не бойтесь править локальную историю. Для этого дайте ей время побыть локальной.

Александр Горбунов, старший iOS-разработчик

image

Если вы нашли ошибку, пожалуйста, выделите фрагмент текста и нажмите Ctrl+Enter.

НазадПредыдущий пост ВпередСледующий пост

Сообщить об опечатке

Текст, который будет отправлен нашим редакторам: