Всегда давайте содержательные и ценные обычные комментарии к запросам на включение
Как очень важная часть цикла разработки программного обеспечения, запросы на вытягивание используются для проверки кода в ветках функций перед слиянием с мастером.
Основываясь на прошлом опыте, проверка кода на самом деле является одной из самых сложных и трудоемких частей всего процесса разработки программного обеспечения. Опытные члены команды часто проводят время за чтением, обдумыванием и оценкой изменений кода, внесенных другими, и предоставляют обоснованную обратную связь по реализации. В 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(Запрос комментариев)
Еще несколько лучших практик для проверки кода:
- Оставляйте как можно больше действенных комментариев
- Группировка похожих комментариев вместе
- Замените «Вы» на «Мы».
- Наставничество окупается экспоненциально