Всегда давайте содержательные и ценные обычные комментарии к запросам на включение

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

Основываясь на прошлом опыте, проверка кода на самом деле является одной из самых сложных и трудоемких частей всего процесса разработки программного обеспечения. Опытные члены команды часто проводят время за чтением, обдумыванием и оценкой изменений кода, внесенных другими, и предоставляют обоснованную обратную связь по реализации. В agile-команде неудивительно, что бесконечные столбцы «На рассмотрении» всегда заполнены.

Следовательно, написание некоторых традиционных и ценных комментариев, которые легко читать и понимать, определенно сделает разработку более эффективной.

Допустим, у нас есть такие комментарии:

@caterpillar
This is not worded correctly

Комментарий выше не очень полезен. Мы не знаем, каково намерение рецензента, так как это может быть истолковано либо как обязательное к исправлению, либо как желательное.

Чтобы сделать намерение ясным, мы можем просто поставить перед комментарием ярлык, чтобы резко изменить тон.

@caterpillar
suggestion: This is not worded correctly

or

@caterpillar
nitpick(non-blocking): This is not worded correctly

Кроме того, ярлык также предлагает рецензенту дать еще несколько полезных комментариев.

@caterpillar
suggestion: This is not worded correctly.
Can we change this to match the wording of the feature documentation?

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

Формат

Чтобы улучшить ожидания читателей и машиночитаемость, мы придерживаемся последовательного формата:

<label>(decorations): <subject>
[discussions]
  • label: Один ярлык для обозначения комментариев, которые мы собираемся оставлять.
  • украшения (необязательно): это дополнительные декоративные метки, заключенные в круглые скобки и разделенные запятыми.
  • тема: основной смысл комментария.
  • обсуждение (необязательно): содержит некоторые подтверждающие заявления, рассуждения и все остальное, что может помочь читателям сообщить «почему» и «следующие действия» для решения проблем, перечисленных в комментариях.

Примеры

issue(blocking): Let's avoid to use this specific method.
If we reference much of a function marked as 'Deprecated', it is certain to disagree with us, sooner or later.

Он может быть автоматически разобран машиной на:

{
  "label": "issue",
  "subject": "Let's avoid to use this specific method.",
  "decorations": ["blocking"],
  "discussion": "If we reference much of a function marked as  'Deprecated', it is certain to disagree with us, sooner or later."
}

Обычно используемые обычные этикетки:

Не стесняйтесь отклоняться от этого конкретного списка ярлыков, если только это кажется уместным.

украшения

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

suggestion(security):I am a bit concerned that we are leaking...
Could we consider using xxx instead?

vs

suggestion(test, if-minor):It looks we are missing some unit tests.

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

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

Дополнительные примеры

nitpick: little start => little bat
Can we update the other reference as well?
chore: Let's run the CI job to make sure it doesn't break anything.
Here are the procedures to run this job
praise: awesome unit tests!

В заключение:

В качестве стандарта для форматирования комментариев, обычные комментарии подходят для любых процессов рецензирования, таких как:

  • Обзор кода
  • Обзор запроса на слияние
  • Экспертная оценка
  • пересмотр
  • RFC(Запрос комментариев)

Еще несколько лучших практик для проверки кода:

  • Оставляйте как можно больше действенных комментариев
  • Группировка похожих комментариев вместе
  • Замените «Вы» на «Мы».
  • Наставничество окупается экспоненциально