Лучшие рекомендации для комментариев по кодовым обязательствам

Ответ 1

Вот мои мысли... все это будет открыто для интерпретации в зависимости от ваших конкретных методологий развития.

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

Учитывая эти идеи, пример коммита для меня будет чем-то вроде

Req3845: Обновлена ​​проверка использования новой проверки RegEx, разработанной в Req3831.

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

Ответ 2

Я префикс каждого абзаца + - * или!

+ means its a new feature
- means feature is removed
* means feature is changed
! means bugfix

Я не думаю, что вы должны подробно описать, какие части кода изменены, потому что каждый VC имеет diff:)

Ответ 3

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

Вам не нужно указывать измененные файлы или ваше имя. Исходный репозиторий может понять это самостоятельно. Описывание изменений также имеет смысл только в том случае, если оно не является нетривиально очевидным из diff.

Удостоверьтесь, что у вас хорошая первая строка, потому что это часто появляется в окне истории изменений, и людям нужно найти вещи по этому поводу (например, туда должен идти номер билета отслеживания ошибок).

Попробуйте зафиксировать связанные изменения в одном наборе изменений (и разделить несвязанные изменения на две коммиты, даже если в один и тот же файл).

Ответ 4

Я пытаюсь следовать тому же правилу, что и для комментариев кода:

Объясните ПОЧЕМУ, а не КАК.

IMO комментарий должен содержать ссылку на проблему (трекер задачи или требование). Какие файлы затронуты, уже доступны в системе управления версиями. Кроме того, он должен быть как можно короче, но все же читаемым.

Ответ 5

Я пытаюсь сохранить свои исправления в отдельных записях.

Я не использую фактический шаблон, а ментальный, и вот так.

Проблема - сводка уровня dev проблема.

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

Ответ 6

Здесь то, что я видел, успешно используется:

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

Ответ 7

Я использую простой метод, описанный Chaosben на JEDI Блог API Windows.

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

• +, если вы добавили функцию/функцию/...
• -, если вы удалили функцию/функцию/ошибку/...
• #, если вы что-то изменили

Выполняя это, другие разработчики могут найти желаемую ревизию намного лучше.

Ответ 8

Во-первых, фиксации должны решить одну проблему (отдельные фиксации для логически отдельных изменений). Если вы не знаете, что писать в сообщении фиксации, или сообщение comit слишком велико, это может означать, что у вас есть несколько независимых изменений в вашей фиксации, и вы должны разделить его на более мелкие элементы.

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

• Первая строка сообщения commit должна содержать краткое описание
• При необходимости префикс, упомянутый выше, сводная строка с префиксом подсистемы, например. "docs:" или "contrib:"
• В следующем абзаце или параграфе описывается изменение, объясняющее, почему и как

Ответ 9

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

Ответ 10

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

Вторая вещь, за которой я следую, - это если есть какая-либо ошибка, связанная с этим, или если ее связанная с какой-либо задачей dev ассоциируется с этим изменением.

Ответ 11

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