Лучшие практики для комментариев к Code Commit
Какой шаблон вы используете для комментариев к коммиту кода?
Один из примеров шаблона:
- (изменение 1): (исходный файл 1.1, 1.2): (подробности внесенных изменений), (почему)
- (изменение 2): (исходный файл 2.1): (подробности внесенных изменений), (почему)
В идеале каждое изменение должно быть сопоставлено с проблемой в системе отслеживания проблем. Этот шаблон в порядке?
11 ответов
Вот мои мысли... все они будут открыты для интерпретации в зависимости от ваших конкретных методологий развития.
- Вы должны делать коммиты довольно часто, с отдельным фокусом для каждого коммита, поэтому, исходя из этого, комментарии должны быть короткими и подробно описывать, в чем фокус был коммит.
- Я фанат публикации того, что в вашем комментарии, с объяснением почему и как подробно в другом месте (в идеале, в отслеживании ошибок). Почему должен быть билет, и после закрытия билета у вас должна быть какая-то заметка о том, как решается эта конкретная проблема.
- Ссылка на вашу систему отслеживания ошибок хороша, если она не обрабатывается иначе (например, взаимодействие TRAC/SVN). Причина этого заключается в том, чтобы указать другим разработчикам правильное направление, если они ищут дополнительную информацию о коммите.
- Не включайте конкретные имена файлов, если исправление действительно сложное и не требуется подробностей. Тем не менее, сложные детали, вероятно, связаны с отслеживанием ошибок с вашими замечаниями по реализации, а не с контролем версий. Надо надеяться, что отредактированные файлы, сведения о различиях и т. Д. Должны быть включены в систему контроля версий, и мы не хотим тратить время на ее дублирование.
Учитывая эти идеи, пример комментария коммита для меня будет что-то вроде
Req3845: обновлена проверка для использования новой проверки RegEx, разработанной в Req3831.
Короче говоря, рассказывает о том, что было изменено, и предоставляет некоторую справку для других, чтобы получить больше информации, не преследуя вас.
Я добавляю к каждому абзацу префикс + - * или!
+ means its a new feature
- means feature is removed
* means feature is changed
! means bugfix
Я не думаю, что вы должны фиксировать подробное описание того, какие части кода изменены, потому что каждый VC имеет diff:)
Если вы используете систему отслеживания ошибок, укажите соответствующие номера билетов.
Вам не нужно упоминать измененные файлы или ваше имя. Исходный репозиторий может понять это сам. Описание изменений также имеет смысл только в том случае, если оно не является очевидным из различий.
Убедитесь, что у вас есть хорошая первая строка, потому что это часто появляется в представлении истории изменений, и люди должны искать вещи по этому (номер билета отслеживания ошибок должен быть указан, например).
Попробуйте зафиксировать связанные изменения в одном наборе изменений (и разделите несвязанные изменения на две фиксации, даже если в одном и том же файле).
Я пытаюсь следовать тому же правилу, что и для комментариев кода:
Объясните ПОЧЕМУ, а не КАК.
ИМО комментарий должен содержать ссылку на проблему (трекер задач или требование). Какие файлы затронуты, уже доступно в системе контроля версий. Кроме того, он должен быть максимально коротким, но все же читаемым.
Я стараюсь держать свои исправления в отдельных проверках.
Я не использую фактический шаблон, но мысленный, и это так.
Issue - сводка проблемы уровня разработчика.
Система отслеживания ошибок имеет все детали управления, и изменения / различия могут быть рассмотрены на предмет изменений кода, поэтому комментарий предназначен для разработчиков, чтобы понять, почему / что в проблеме.
Я использую простую технику, описанную Chaosben в блоге JEDI Windows API.
Для быстрого просмотра изменений, внесенных в репозиторий, мы предлагаем написать краткие краткие комментарии, начиная каждую строку с одного из этих символов:
- + если вы добавили функцию / функцию /…
- - если вы удалили функцию / функцию / ошибку /…
- # если ты что-то изменил
Делая это таким образом, другие разработчики могут найти желаемую ревизию намного лучше.
Во-первых, коммиты должны решить одну проблему (отдельные коммиты для логически отдельных изменений). Если вы не знаете, что писать в сообщении коммита, или сообщение comit слишком длинное, это может означать, что у вас есть несколько независимых изменений в вашем коммите, и вы должны разбить его на более мелкие элементы.
Я думаю, что соглашения о фиксации сообщений, ожидаемые и используемые git, имеют большой смысл:
- Первая строка коммита должна содержать краткое описание
- При необходимости префикс упомянутой выше итоговой строки с префиксом подсистемы, например, "docs:" или "contrib:"
- В следующем параграфе или параграфах опишите изменения, объяснив, почему и как
Вот то, что я видел, использовал успешно:
- Ссылка на номер ошибки или идентификатор функции
- Краткое описание изменений. Что было изменено.
- Рецензент кода (чтобы убедиться, что он у вас есть), если он не обрабатывается системой регистрации.
- Имя тестера или описание того, какие тесты были проведены (если вы запаздываете и вы очень осторожны)
Если два файла были изменены по разным причинам, они должны быть в разных коммитах. Единственный раз, когда вы должны фиксировать более одного файла кода одновременно, это потому, что все они принадлежат одному и тому же исправлению / изменению.
Там нет жесткого и быстрого правила, как его простой английский. Я пытаюсь объяснить проделанную работу в минимально возможных словах. Любой, кто ищет историю изменений, просто хочет знать, что произошло в конкретном изменении. Если кто-то хочет получить более подробную информацию, то это есть в коде.
Во-вторых, я следую, если есть какая-либо ошибка, то вставьте ее или, если она связана с какой-либо задачей разработчика, то свяжите это с изменением.
Имейте в виду, что если кому-то нужны подробности того, что изменилось, они могут получить разницу. Тем не менее, я просто обычно пишу одно или два предложения для каждого существенного изменения, а затем в конце вносим мелкие исправления.