Какую информацию должен содержать комментарий о компиляции файла SVN/версии?

Мне любопытно, какой контент должен быть в комментариях о компиляции с версией. Должен ли он в целом описать, что изменилось (например, "Экран виджета был изменен для отображения только активных виджетов" ) или должен быть более конкретным (например, "Новое условие было добавлено к предложению where запроса fetchWidget для извлечения только активных виджетов по умолчанию" )

Как атомный должен быть одним фиксатором? Просто файл, содержащий обновленный запрос в одном коммите (например, "Обновлен экран виджета, чтобы отображать только активные виджеты по умолчанию" ), или если это и несколько других изменений + изменения интерфейса на экране имеют одно и то же сообщение с более общим описанием ( "Обновлен экран виджета: A) отображает только активные виджеты по умолчанию B) добавлена кнопка для переключения неактивных виджетов" )

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

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

Ответ 1

Некоторые рекомендации:

не записывайте вещи, которые система VC уже отслеживает автоматически: какие файлы, сколько строк, когда, кто внес изменения...
напишите, какова цель изменения: "добавьте поддержку UTF-8 для тегов ID3"
если вы обнаружите, что цель нечеткая или множественная, вам, вероятно, лучше делать несколько коммитов. Линус Торвальдс может уйти с написанием "разных исправлений повсюду"; остальные не должны брать его в качестве примера.
Если у вас есть какая-то система отслеживания, которая присваивает уникальные идентификаторы проблемам или запросам функций, обязательно комментируйте этот комментарий этим идентификатором.

Ответ 2

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

Ответ 3

Полезными комментариями коммита являются те, которые добавляют полезную информацию, которую нелегко извлечь из самих изменений. Глядя на diffs, вы увидите, что изменилось, поэтому комментарий коммита должен сосредоточиться на объяснении ПОЧЕМУ были сделаны изменения:

Исправлен сбой из-за разыменования указателя NULL (идентификатор ошибки 234).
Добавлена команда для отключения от сервера (запрос функции 22).
Очищенный код для будущих изменений.

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

Добавлена поддержка, позволяющая пользователю frobulate виджета.

Ответ 4

Лично я пытаюсь сделать краткий обзор того, что я изменил и/или добавил. Что-то, что напомнит мне: "О да, это [вероятно], где я добавил это дополнительное правило для бизнес-объекта". Потому что я всегда могу запустить "diff", чтобы увидеть, что изменилось.

Ответ 5

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

Ответ 6

Он должен содержать небольшое резюме изменений (чтобы разрешить фильтрацию в списке изменений) и почему было применено изменение.

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

Ответ 7

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

Мне также очень полезно устанавливать теги в комментариях коммита, например #doc, #typo, #refactor,...

Я бы не стал слишком описательным при совершении - причины для чего-то так или иначе должны быть в документации или в комментариях кода IMO.

Ответ 8

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

Разрыв строки для большей читаемости.

Используйте точки для разделения связанных групп изменений.

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

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

создать маршрут, чтобы получить новый пост от постановки, обновить базу данных, получить RSS-канал, добавить

PDO для кеширования. удалите сценарии отслеживания нижнего колонтитула в среде разработки.

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

незначительный.

или же

создать маршрут, чтобы получить новый пост от постановки, обновить базу данных, получить RSS-канал, добавить

PDO для кеширования. удалите сценарии отслеживания нижнего колонтитула в среде разработки. незначительный.

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

ошибка комментирования, строка № 14.