Какая информация файл SVN/Versioned должен фиксировать комментарий, содержат?
Мне любопытно, какое содержание должно быть в имеющем версию комментарии фиксации файла. Если это обычно описывает, что измененный (например, "Экран виджета был изменен для отображения только активных виджетов"), или если это более конкретно (например, "Новое условие было добавлено к, где пункт fetchWidget запрашивают для получения только активных виджетов по умолчанию"),
Как атомарный сингл должен фиксировать быть? Просто файл, содержащий обновленный запрос в единственной фиксации (например, "Обновленный экран виджета для отображения только активные виджеты по умолчанию"), или если это и несколько других изменений + интерфейсные изменения в экране совместно используют ту же фиксацию с более общим описанием как ("Обновленный экран виджета: A) отобразите только активные виджеты по умолчанию B) добавленная кнопка для переключения показывающих неактивных виджетов"),
Я вижу комментарии фиксации подверсии, используемые очень по-другому, и задавался вопросом, с чем другие имели успех. Некоторые комментарии так же кратки как "обновленные файлы", в то время как другие являются многими абзацами долго, и другие отформатированы способом, что они могут быть запрошены и связаны с некоторой внешней системой, такой как JIRA.
Я раньше был чрезвычайно описательным причины изменения, а также определенных технических изменений. В последнее время я сокращал и просто давал генералу, "Это - то, что я изменил на этой странице" вид комментария.
7 ответов
Некоторые рекомендации:
- не пишите то, что система VC уже отслеживает автоматически: какие файлы, сколько строк, когда, кто сделал изменение...
- пишите, какова цель изменения: "добавить поддержку UTF-8 в ID3-теги"
- если вы обнаружите, что цель неясна или множественна, вам, вероятно, лучше сделать несколько коммитов вместо этого. Линусу Торвальдсу может сойти с рук написание "различных исправлений повсюду"; остальным не стоит брать с него пример.
- если у вас есть какая-либо система отслеживания, которая присваивает уникальные идентификаторы проблемам или запросам функций, то, конечно, пометьте комментарий этим идентификатором.
Лично я стараюсь сделать краткое резюме того, что я изменил и/или добавил. Что-то, что напомнит мне: "Ах да, здесь [вероятно] я добавил это дополнительное правило к бизнес-объекту". Потому что я всегда могу выполнить "diff", чтобы увидеть, что именно изменилось.
Если вы используете систему отслеживания ошибок, лучше всего указать ошибку / улучшение #, над которой вы работаете, которая применяется к изменению. Много раз вы все равно будете просто переписывать то, что находится в описании ошибки.
Оно должно содержать небольшое резюме изменений (для возможности фильтрации в списке изменений) и причину, по которой было применено изменение.
Документация нового кода должна быть в самом исходном коде, а не в сообщении журнала. (А комментарии, которые только относились к старому коду, должны быть удалены. Вы всегда можете просмотреть эти старые комментарии через историю вашей системы SCC).
он должен кратко объяснить, что содержит коммит. Это должно включать номер заявки на исправление ошибки или улучшение. Лучший совет, который я когда-либо слышал о написании комментариев, - это «Кодируйте, как будто следующий человек, который будет поддерживать ваш код, - это маньяк-убийца, который знает, где вы живете». Это в равной степени подходит для коммитов комментариев.
Одна вещь, которая помогает мне при размышлениях о том, что писать / что не писать, заключается в том, что в конечном итоге должна появиться возможность компилировать внутренние технические примечания к выпуску из комментарии к фиксации.
Я также считаю очень полезным устанавливать теги в комментариях к коммитам, например #doc, #typo, #refactor, ...
Я бы не стал слишком описывать коммит - причины для того, чтобы что-то сделать. так или иначе должно быть в документации, или в комментариях кода IMO.
Полезные комментарии к коммитам - это те, которые добавляют полезную информацию, которую нелегко извлечь из самих изменений. Просмотр диффов покажет, что изменилось, поэтому комментарий к коммиту должен быть сосредоточен на объяснении того, ПОЧЕМУ были сделаны изменения:
Исправлено падение из-за разыменования указателя NULL (ошибка ID 234).
Добавлена команда для отключения от сервера (функциональный запрос 22).
Очищен код для будущих изменений.
Другой полезный вид комментария - это комментарий, который резюмирует общую цель большего набора изменений:
- Добавлена поддержка, позволяющая пользователю фробулировать виджет.