Comments 81
UFO landed and left these words here
UFO landed and left these words here
вы знаете, практически по любой теме можно написать текст любого объёма =)
Т.е. на изменение 4х строчек css вы написали 6 строчек описания? Нет, я конечно согласен, что нужно писать расширенное описание, но не до такой-же степени!
Да, именно так. Причем, возможно, эти 6 строчек спасли мне два часа отладки, когда через неделю я буду искать баг, который случайно привнёс этим комитом. Или спасёт кому-то еще часы работы, когда он будет искать в логе ревизий то или иное изменение этого файла.

Тут идёт впечатление из опыта работы. Да, это замедляет каждый комит, но ускоряет работу в целом.
если человек может 4мя строчками цсс создать баг то это значит что он совсем ничего не понимает в текущем состоянии дел и ему лезть в цсс точно не стоит. И когда логи комита будут огромными тоже будет трудно понять что происходило. нужно ко всему подходить здраво.
Не все разработчики идеальны, как и все люди, и, как и все мы, могут совершить ошибку, особенно в большом проекте. Если бы ошибок не было… Эх! Это было бы счастье! :)
Свидетельствую: даже одна строчка в css может через пару дней оказаться тем камешком, из-за которого расползётся, например, весь лэйоут в эксплорере. И если человек не знает что там что-то изменилось — это может привести к появлению еще двадцати ненужных строчек которые все это фиксят через жопу.
Да. еще можно в комменты добавлять цитаты из баша — и количество строк кода повышается и дебажить становится не так скучно ))))
В целом я согласен с вами. Кстати говорят что девушки кодеры больше чем мужики комментируют код. Надо бы нам в фирму парочку ))))
Описание комита пишется один раз, а читается — значительно чаще. И труднее, если это описание а-ля «поправил баг»
Экономить на написании — терять потом. Сомнительная экономия.
Мне кажется в этом случае проще посмотреть diff коммита, нежели извращаться с описанием.
Возможно, но тогда надо писать лог «смотри дифф». И потом если таких логов много, плюешь на всё и ищещь багу другими путями или перестаешь читать историю. Потому что её хочется именно читать, а не тыкаться в диффы ко всем ревизиями, некоторые из которых могут быть маленькими… А вот некоторые — совсем нет. Да и замысел автора из диффа чаще всего неочевиден.
Я не спорю, но если изменение настолько мелкое, как исправление 4-х строчек в css, достаточно было бы минимальных комментариев без описания что сделано, ибо дифф скажет все. В общем, тут как и в стандартном подходе к комментариям в коде — много — плохо и мало плохо. Если посмотреть diff действительно достаточно, развернутое описание — это трата времени.
Постоянно ругаюсь с коллегами на эту тему :(. Комменты не пишут к коммитам, очень напрягает, когда видишь обновление файлов, закачиваешь и не понять, что к чему. Нужно бегать смотреть, кто его закинул и потом спрашивать, чего поменялось. Либо делать диффы. Бррр…

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

За кракозяблы и «123» вместо развёрнутых комментариев программистам по шапке :)
А еще лучше ввести шаблон лога, который бы стимулировал заполнять некоторое количество обязательных полей (номер тикета, и т.п.), а также писать само описание комита, ну и, поддерживаю, проверять это в момент комита ;)
Ссылок на таски/тикеты тоже не вседа хватает. Чтобы понять для чего коммит надо идти по ссылке/найти описание тикета. Так что помимо ссылки, стоит дать небольшое пояснение.
Согласен, нужно чётко описывать свои изменения. Сам же через день можешь забыть что сделал.
Обычно пишу в этот лог тему и номер тикета (обращения), я обычный программер а не секретарша. Раньше вообще ничего не писали, теперь руководитель проекта обязал, я его обычно слушаюсь :)
Вот мой пост про то, что этого маловато бывает. Это мой личный опыт, может кому-то это будет полезно. Сам как руководитель разработки заставляю уж как минимум ссылку на тикет и текст изменения давать в логе, но хочется и большего часто.
по опыту тестера скажу, что удобней всего когда в лог ветки идёт краткое описание изменений, а в коммит мержа ветки в транк только номер тикета и его название, а уже в тикете надо заставлять программиста оставлять заметки, что он в тикете набедокурил.
Мне, как руководителю, например, не очень хотелось бы видеть в SVN log очень уж расширенное описание к каждому коммиту. Достаточно указание на ишью id таска/фичи/бага и краткое словесное описание того что сделано, без тонкостей реализации. Расширенное описание допустимо в таск трекере (если конечно оный применяется).
А как после этого по логу ревизий оценить что случилось с файлом в каждой из ревизий? Я довольно часто сталкивался с такой задачей. Например, я вижу, что большой и сложный модуль (или группа модулей) начал давать сбои. Первая моя мысль — проглядеть комиты в него за последний месяц (если я знаю, что месяц назад всё было хорошо). При этом часто оказывается, что разработчик, работая над фичей XXX комитит изменения в модуль YYYY, который вроде бы к этой работе отношения не имеет (комитит намеренно или просто случайно). Грубо, решали проблему «съехавшей ссылки» а изменили модуль ORM, как по логу «Фикс съехавшей ссылки» понять, что случилось с ORM-подсистемой? А часто такой комит затрагивает несколько файлов, имея общий лог с общей фразой (что тоже зло, по-моему).
Имхо решается административно — делить фичи на подфичи, не допускать коммитов в принципиально разные модули в один коммит. Имхо это проще, чем потом разбираться в адской простыне, где к каждому коммиту описание в виде «в методе ххххх добавлен параметр ууууу типа zzzzz, используется в строке nnnnn blah blah blah». Основная беда таких расширенных описаний — «за деревьями не увидишь леса». Если мне что то непонятно по коммиту — сразу же уточню у автора, если что попрошу откорректировать описание.
Попробую возразить. Иногда как раз одна маленькая фича затрагивает большие куски кода (маленькой она казалась только на первый взгляд). Ну а разработчики имеют свойство болеть, уходить в отпуск, менять работу, а еще забывать то, что они сделали. Иногда для меня лог комита — единственное, что позволяет вспомнить, что же я сделал, если это было год или полтора назад ;)

Но это дело вкуса, конечно. Я не говорю, что надо описывать какие-то детальные изменения, но если, например, изменена логика работы метода, она должна быть описана, если метод добавлен, то должно быть написано его предназначение. Вряд ли будет интересно знать из лога его параметры и т.п., но зачем он нужен и что он делает — вот это главное, по-моему. И в чём была мотивация его создания.
полностью согласен
вообще по-моему самое адекватное описание к комиту — это минимально возможная строка описывающая пофикшеную проблему
все остальное должно решаться другими методами. начиная от нормально откоментированного кода (где кстати это правило тоже применимо) до административных мер.
мы пробовали у себя ставить длинные описания после чего все взвыли тк
— в хистори изменений стало разбираться просто нереально из-за «простыней»
— придумывать и описывать что ты сделал занимает существенное время в случае таких описаний
— тех задач, которые должны решать такие описания, а именно последующее разбирательство все равно этот метод не решает, тк видя простыню разработчик как правило идет и спрашивает человека, при этом его отвлекая на полчаса.
Между прочим отличный совет для правильного ведения ревизий кода. Взять например несколько коммитов и их логи — одни номера тикетов, никакой сути. Приходится еще поднимать тикеты и вникать в его историю, чтобы понять ревизию кода.
А нет ли таких сред разработки, чтобы открыв тикет и введя код автоматически добавлять коммит ссылающийся на тикет, учитывать затраченное время, создавать отчёты и т.д.?
Точнее, из логов комитов можно делать trac-ссылки на тикеты и другие комиты. И наоборот, из тикетов делать ссылки на комиты. Совсем полной автоматизации процесса там нет, имхо.
Насколько «совсем полной»? Коммитом можно закрыть тикет или добавить к нему комментарий.
У нас используется Hudson в качестве build-системы, Jira — баг трекер и Svn. В комментариях к комиту указываем номер бага, по которому произошел комит, ну и может пару слов, если есть чего добавить. Никаких соплей и размазни, если это уже описано в баге и не сделано никакой дополнительной работы, таким макаром у нас не получается никакого дублирования того, что уже описано баг трекере. Hudson, во время билда проверяет комменты и в случае совпадения номера бага в Jira постит туда коммент — «По этому багу были зачекинены файлы такие-то» со ссылками на соответствующие ревизии файлов в svn. Очень рекоммендую.
2Г-н smira, вы не обижайтесь, но похоже как руководитель разработки вы очень занудный товарищ.
Может, я зануден, не мне судить :)

Но всё-таки я хочу подчеркнуть, что я говорю не о дублировании. А о документировании изменения как такового.

Могу привести пример: изменение может даже путешествовать между проектами, жить в виде патча и т.п., когда оно отделено от системы контроля версий. И лог ему нужен. И я писал про то, что лог как раз не дублирует информацию тикета, а дополняет её.

Само собой, автоматизация — трекер + VCS. Но попытка задуматься и написать нормальный лог упорядочивает программирование, вот что я хотел сказать. А копи-паст из тикета или просто ссылка на него не заставляет задуматься, это механическое действие.
Ну в целом я с вами согласен. Если это поможет уточнить задачу, или понять что-то -всегда пожалуйста. Главное, не создавать нескольких источников для такой информации, чтобы не приходилось после баг-трекера еще и в логи vcs лезть. Если что-то можно сказать по поводу данного конкретного коммита, то конечно пусть будет коммент, не повредит так точно.
Думаю, не для всех коммитов нужны комментарии. Для ключевых моментов обязательно нужно, для исправления багов по списку тоже. Но не для всех абсолютно.
Вот если бы заранее знать, для каких не надо точно… Я бы тоже не писал. Мне кажется, что так как заранее не угадаешь, лучше писать всегда :)
лично пользуюсь только линками на tickets. тоесть «работал над вот этим».
реже пишу название компонента над которым работаю.
понимаю проблему информативности, но… время… время… время…
Я пытался как раз написать о том, что лог комита экономит время. Т.е. время, затраченное на его написание, окупается. Хотя «лень», и хочется «побыстрее»…
Я для себя и своих проектов принял такую систему: каждое изменение в коммите описывается одной строкой вида «[+] Краткое описание изменения (+номер тикета, если был)».
При этом знак в начале строки имеет определенный смысл:
[+] — добавлена новая функциональность
[-] — исправлен баг
[*] — улучшение существующей функциональности.

Можно придумать и еще группы, под себя.

В итоге из списка логов коммитов за период между версиями можно собрать аккуратный список того, что сделано в текущей версии, и сразу вставить это в change log.

P.S. У многих видел использование того же принципа, но с расширенным написанием, например:«[BUG] [ENH] [NEW]».

Независимо от чьих-то рекомендаций и советов (не было их), как только начал пользовать SVN, сам стал описывать изменения в ревизии с префиксами:
+ — добавление функциональности;
- — удаление ненужных кусков;
± — изменение с целью улучшения, исправления ошибки.

Не задумывался о том, что тема правильности ведения лога изменений будет вообще где-либо поднята/обнаружена мною, но тем приятнее совпадение мнений:
а) лог коммита — это не просто так, а очень даже может помочь;
б) писать в него надо словами, кратко «проговаривая» каждое изменение;
в) применение символических обозначений улучшает читабельность за счет сокращения количества повторяемых слов;

Совпадение мысли с другой статьей Искусство тратить минуты, экономя часы тоже нашло выражение =)
Для сокращения времени описания правки «потом» при коммите, сразу добавляю описание очередного изменения в файл-заготовку, как только модуль удачно скомпилировался. Добавил новую функцию — в коде откомментировал ее назначение, параметры, важные моменты в реализации, в заготовку лога коммита отписываю:
+ имя_функции(вербализованное, описание, параметров): чего возвращает.
Я не думаю, что в лог нужно писать, какие конкретно изменения делаются в коде. Для этого проще смотреть различия между ревизиями. А функция в коде должна иметь понятный комментарий. В лог нужно записывать краткое описание сделанных изменений в плане изменения функциональности приложения.
Не какие именно (добавил/удалил/изменил), а описывать их! Зачем, почему и т.п. Как называется добавленный параметр, какого он типа и т.п. — это всё видно из дифа, а вот зачем? На этот вопрос обычно диф не ответит, и он скрыт в голове программиста :)
Зачем, почему и т.д. видно из хорошо документированного кода. Если, конечно, там хаки не плодить (и писать в лог, чтобы самому не забыть потом). Когда приложение имеет четкий и регламентированный каркас (MVC, multi-layer и т.д.), то, в принципе, работа сводится к написанию основной функциональности, и больших вопросов «почему» возникать не должно. Вроде бы так.
Ну это только в теории. На практике всегда, даже в самом хорошо организованном коде становится понятно, что структура и организация неидеальны. Это становится понятно не сразу, а потом, по мере роста кода. Переписывать времени/денег нет.

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

Также и с логом комита. По началу кажется, что одного достаточно, потом добавляется еще что-то, он лучше структурируется и т.п. Это такой бесконечный итерационный процесс, прогресс ему имя, наверное :)
«Наверное, многие замечали, что иногда достаточно подойти за помощью к другому разработчику и рассказать о проблеме, чтобы тут же в голове появилось решение.»

Вот за это — респект!
Открыл svn, последний коммит:

«КАММИТ ОПАСТНОСТЕ!!!
Внимание — если обновиться то ничего работать не будет»
Особенно радовало, когда человек уходил домой в пятницу вечером перед релизом, забыв залить все свои изменения. И не выстрелишь тут, он уже ушел домой.
Перед релизом комитить — это неправильно ;) Стабильная ветка должна предшествовать релизу :)
Хм, о комментариях к коду сломано много копий, думаю, здесь тема чем-то пересекается. И отношение к логам коммитов у меня схожее — комменты нужны, но они должны быть во-первых, достаточными, во-вторых, не излишними. Комментарий, который повторяет код — плохой комментарий. Комментарий к коммиту, который повторяет diff — имхо, тоже плохой комментарий. Думаю, в вышеозначенном примере можно было ограничиться «Сделал отступ 10 пикселей между блоками А и Б. Тикет: #1734»
Я своим постом хотел подвести, в частности, к этой мысли. Именно не повторять дифф и не повторять код, а давать что-то новое и важное по сравнению с кодом. Пример с CSS у меня неудачный, видимо. Спасибо.
Видимо ваша статья как-то отображает внутренние рабочие процессы которые я понять не могу :)
С чем мне приходится работать:
1. git — в качестве системы работы версий (+ вебморда какая-то)
2. FogBugz — для ведения тикетов

Лог коммита (тм) содержит:
1. Если он относится к тикету, то тикет + его название (вебморда линкует его при просмотре коммитов)
2. Если это большое нововведение, то скорее всего там будет ссылка на внутреннюю вики, либо краткое описание + список того что надо потестировать
3. Мелочь всякая -> просто краткое описание, суть видна из диффа (в той же вебморде все отлично видно)

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

В общем, если есть в компании общепринятая культура ведения всего этого, то жить гораздо проще становится, без сочинений в логах :)
Я чувствовал, что мой пост вызовет много возражений. Мне хотелось тут не в большей степени рассуждать о том, что лог должен содержать (а примерно то, что Вы пишите, он содержит у нас), а то, что написание разумного лога (до некоторой степени самодостаточного) позволяет улучшить качество программирования. Лог не может быть полностью самодостаточным — нужен тикет, чтобы понять зачем вообще это изменение затевалось (если задача решается серией комитов). Но всё-таки по отношению к изменению непосредственному он должен быть максимально автономен, то есть по логу должно быть понятно, что же именно поменялось и зачем в этом файле. Общая идея, склеивающая изменение — в тикете, в вики общая документация по коду/модулю. А каждое изменение заслуживает своей доки, опять-таки имхо. Я в конце писал о том, что именно написание самого лога упорядочивает мысли и позволяет выявить ошибки в коде.
Офигеть. Вы смогли фразу «всегда подробно и по-человечески описывайте в коммите проделанные изменения» растянуть на 5 килобайт текста о_О
Несколько недель назад перевел команду с SVN на Mercurial, им стало чуть менее удобно работать (хотя это скорее всего субьективно, привыкнут), а мне стало намного удобнее — очень удобный лог, и очень легко посмотреть историю. Если надо понять что произошло на протяжении времени, выбираешь два коммита, запускаешь visuall diff (Araxis Merge) — из-за того, что репозиторий локальный, все открывается моментально — и разбираешься (в т.ч. и код ревью). Длинные названия коммитов не сильно помогали бы, но это лично мне, кому-то наверное будет удобно.
Слишком много времени уходит на подобные подробные описания к комитам… (
Мы сделали так — в логе пишутся комментарии с префиксами (FEATURE, BUGFIX, TOTEST, INTERNAL, ...). А в ночном билде утилиткой билдятся несколько changelog'ов — для заказчика (FEATURES + CHANGES), для тестеров (всё, кроме INTERNAL + ONREVIEW + ...) и т.д.
В итоге — никому не надо писать отчётов в конце недели или после очередного билда, т.к. всё «пересчитано».

Неделю попривыкали, а теперь незаменимо ;)

// всё что можно автоматизировать — надо автоматизировать

//// пустой лог или без префикса — можно просто не пропускать при коммите
Лог коммита — это резюме изменений. Часто это всего лишь выполненная задача/тикет плюс минимальный комментарий по способу ее выполнения. И не надо бояться диффа — благо средств для нечеловечески приятной работой с ним есть масса (применительно к php мне лично нравится реализация в Eclipse).
> Лог комита может содержать дополнительную мета-информацию: номер тикета, имя человека, который провел code-review, ссылки на другие комиты и т.п.

Если впридачу к системе контроля версий есть еще вторая, где тикеты и учет code-review, плюс понимание, зачем всё это нужно, то почему бы не выбрать третью систему, которая одна может и то и другое? По меньшей мере вопрос, вынесенный в заголовок, решиться сам собой :)
А у нас бывало сотню+ ревизий в день — мы бы ахуели писать столько логов коммита ) Нам бы понадобился отдельный батальон индусов-логгеров коммита )
Может быть стоит делать коммиты реже, но по-объемнее?) А то коммит каждый 5 минут… При багфиксинге еще нормально, но при обычной разработке мне кажется слишком мелко. Если конечно у вас не команда программистов в 30 — 50 человек, работающая над огромным проектом :) ИМХО.
Комит должен быть атомарным, желательно делающим одно конкретное изменение. Так что сколько комитов в день — это сложный вопрос. Один человек за день, имхо, может сделать разумно десять-пятнадцать комитов, всё остальное — это уже какие-то технические вещи (например, мерж).
Я не спорю про атомарность, но мне кажется размер «атома» не должен быть слишком мелким. Атомарность != маленькие задания/коммиты. Вы сами выбираете уровень абстракции и «размер» атома.

Ведь разбить можно по разному, можно на маленькие кусочки, типа «сделать у картинки margin 10px», «сделать у картинок border», а можно написать «изменить визуализацию картинок: верхний margin 10px, border 1px». Это простенький пример, но коммит для второго тикета тоже будет атомарным, касающимся только отображения картинок, но это позволит не делать кучу мелких изменений, а решать конкретные задачи.

Но даже этот пример немного не в тему, это всетаки больше исправления, чем решение новых задач. Мне кажется, что задачи не должны быть на 5 минут, иначе это не задачи. Потому что переключение разработчика с одной такой мелкой задачи на другую займет время, лучше давать задания типа «Реализовать адаптер для авторизации пользователей, с кодированием важных данных с AES_ENCRYPT, и хэшированием пароля». То есть такое задание приведет к большему коммиту, займет больше времени, но разработчик будет спокойно решать свою задачу, и когда она будет готова — закоммитит новый класс в репозиторий.

Вот как-то так я хотел сказать :)
Совершенно согласен! Только мелкий комит неатомарен, потому что не покрывает минимальную единицу изменения, а слишком большой неатомарен, потому что в нём несколько явных замыслов и идей.

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

Т.е. атомарность, имхо — это очень субъективная штука.

Как-то так ;)
Угу) Пора мне начинать пользоваться репозиторием, хоть на собственном опыте пойму все эти вещи, о которых написано в статье, и о которых мы сейчас по-дискутировали :)
Если не ошибаюсь, то в SVN 1.5 в списке фич уже есть разделение файлов на группы внутри одного коммита (ревизии) и отдельные комментарии для этих групп. Т.е. можно коммитить одновременно несколько задач, но разделить файлы, изменения и комментарии по задачам.
Очень здорово, когда система баг-трекинга и вершн-контроля работают вместе. В каждом коммите пишешь номер бага. Лог коммита добавляется комментом в баг вершн-контроля.

При таком подходе можно ответить на многие вопросы, например:
  • Кто и как пофиксл этот баг?
  • Нафига он закоммиттил эту херню?
  • Ага, кто-то закоммитил что-то под мой любимый баг, неужели зафиксили?
  • А над чем это Тяпкин-Ляпкин работает последние два года?
Да, это так. Но не позволяет понять, почему было сделано конкретное изменение. Например, в процессе работы над какой-то фичей я могу внести в интерфейс дополнительный метод. А зачем я это сделал? От того, что работал над фичей? Нет, у меня была более конкретная мотивация, которая является частью изменений этого конкретного модуля. А ссылка на тикет обязательна.
Не-не, я не критикую, а дополняю.

Я, наверное, не точно сказал: в каждом коммите не только номер бага, но и описание изменений. Без описания — никак :)
Лог комита может содержать дополнительную мета-информацию: номер тикета, имя человека, который провел code-review, ссылки на другие комиты и т.п.

А что, есть еще системы управления версиями, где номер тикета и ревьюер пишутся в описание коммита, а не в отдельные мета-поля? :)
А они и пишутся прямо в лог, просто используется шаблон, чтобы это выглядело красиво и единообразно, и чтобы можно было автоматически это распарсить. Примерно как в посте в примере про CSS. Это называется 'commit template' обычно.
Почитал. Всё правильно, но для готовых/полуготовых проектов. На стадии активной разработки я меняю за день не один файл. В одном изменений много, а в другом просто удалил пустую строку. И вот в конце дня я делаю комит и… конечно же я не буду писать коментов для каждого файла. Допустим, мои коллеги сделали то же самое. Не страшно, потому что в начале следующего дня я сделаю синхронайз (работаю в Zend for Eclipse и использую встроенную поддержку svn), увижу все файлы, которые подлежат апдэйту, если необходимо, тут же сравню локальную и удалённую версию и только после этого сделаю update. В совокупности с тем, что каждая функция комментируется в коде, прописываются TODO и т.д., такой подход никогда не вызывал сложностей у разработчиков.
Ах да, как быть с не разработчиками? Развёрнутый комент к ревизиям по ходу проекта будет давать этим людям представление о общем ходе реализации.
Как раз наоборот, мой пост говорит об обратной практике. О том, что надо структурировать разработку, тогда можно будет меньше заглядывать в дифф (если не нужен code review), а самое главное, это позволит именно упорядочить свои мысли в конце дня и вместо комита с логом «день закончился» будет в течение дня серия осмысленных комитов, производящих осмысленные изменения. Часто невозможность это сделать и необходимость делать какие-то временные комиты (например, добавить срочно функцию в интерфейс в интересах другого разработчика) говорит о том, что в процессе разработки что-то не так (сугубо моё личное мнение, не обобщаю...)
Only those users with full accounts are able to leave comments. Log in, please.