Лучшие практики для комментариев контроля версий

Question

Есть много разговоров о комментировании кода, но как насчет комментирования регистрации?

Я нашел это сообщение в блоге: http://redbitbluebit.com/subversion-check-in-comment-great-practices/

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

В настоящее время мы определили нашу собственную схему с <Begin_Doc>...<End_Doc> для всего, что должно быть опубликовано для наших клиентов программного обеспечения. Но даже для внутренних вещей я хотел бы знать «почему» для каждого изменения.

Answer 1

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

Answer 2

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

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

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

Вам необходимо определить, что такое репозиторий Source / version / SVN - для управления исходными файлами или для написания заметки о выпуске. Я думаю, что это не должно быть перегружено.

Answer 3

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

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

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

Answer 4

Рекомендую функциональные комментарии. Комментарии должны дать резюме того, что было изменено. Если что-то изменилось и почему. Каждый коммит должен быть объяснимым, если вы не можете объяснить это ясно, вы, вероятно, не должны проверять это.

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

Мое личное предпочтение в этом стиле:

ОБНОВЛЕНО система регистрации ошибок.

1. Добавлена ​​устаревшая процедура анализа ошибок с использованием регулярных выражений для получения устаревших кодов ошибок.
2. Изменен текст в сообщениях об ошибках базы данных, чтобы исправить ошибки в написании.
3. Удалены закомментированные разделы кода, потому что они больше не использовались.

Answer 5

Согласитесь с Remembrance, но вы также должны написать немного о том, почему вы реализовали изменение / исправление ошибок так, как вы это сделали. Если вы верите в частую регистрацию, вам также следует включить TO DO, чтобы один из ваших коллег мог выполнить задачу.

Answer 6

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

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

Также, если вы используете такой инструмент, как FogBugz , вы можете связать регистрацию SVN с номером дела. Это означает, что вы можете просмотреть дело, чтобы получить полное обсуждение, комментарии, скриншоты и т. Д. Это гораздо больше информации, чем вы могли бы ввести в комментарии для проверки.

Answer 7

В наших проектах мы всегда выступаем за то, чтобы предоставить некоторую информацию о том, что такое коммит, и помочь избежать необходимости дублировать информацию, такую ​​как проблема, которую мы используем Trac, и интегрировать наш репозиторий. Преимущество состоит в том, что вы можете ссылаться на билет вопроса в комментарии и указывать только разрешение или шаги выполненной работы. Затем Trac автоматически связывает ссылочный номер с исходным номером проблемы и применяет ваше сообщение о коммите в качестве комментария к проблеме. Затем, когда вы захотите увидеть, что было сделано, вы можете просто прочитать проблемы в Trac и получить полный контекст.

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

Answer 8

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

Комментарии для проверки должны быть той информацией, которая нужна разработчику: это включает рефакторинг, мотивацию кода и т. Д.

Answer 9

Редактировать: Учитывая, что это мой самый отрицательный ответ, я думаю, что стоит подчеркнуть то, что скрыто в последнем абзаце: я являюсь единственным владельцем. Я на 100% владею этими проектами и не работаю с другими разработчиками. В магазине с более чем одним разработчиком все, что я говорю в этом ответе, может быть совершенно противоположным.

Я подписываюсь на DRY здесь, как и во всех вещах.

Я почти никогда не добавляю комментарии к своим коммитам. Комментарий почти всегда повторяется. Ответ на вопрос «что изменилось в этом коммите»? почти всегда в разн.

Когда я смотрю на файл и спрашиваю «что, черт возьми, здесь произошло?», Первое, что я делаю, это смотрю на diff с предыдущей версией. В 90% случаев ответ сразу становится очевидным, либо потому, что код самоочевиден, либо потому, что было что-то неочевидное, что я прокомментировал в коде. Если это не так, я сопоставляю даты версий файла с системой отслеживания ошибок, и ответ там.

Это всегда работает. Иногда требуется небольшое исследование, чтобы что-то выяснить, потому что я не прокомментировал свой код адекватно. Но я так и не смог найти ответ достаточно быстро.

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

(«Почему бы вам не прокомментировать такое изменение в истории изменений в верхней части файла?» - спросите вы. Я не храню историю изменений в верхней части своих файлов. Это было страшно изменения, которые нужно изменить, и я ни разу не пожалел об этом. История изменений - Subversion.)

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

Answer 10

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

Если вы используете что-то вроде интеграции Trac или roundup + svn, он может выбирать номера выпусков из сообщений фиксации. Я бы всегда помещал их в первую строку, поскольку они очень полезны.