День восемьсот восемьдесят первый. #BestPractices #CodeReview
Лучшие Практики для Эффективных Обзоров Кода. Окончание
Начало
5. Давайте конструктивную обратную связь
Взаимная проверка кода направлена на повышение производительности команды, а не на разжигание конкуренции между автором кода и рецензентом. В любом случае код необходимо проверять. И если разработчики воспринимают это как процесс обучения, а не критику своей работы, это способствует общему успеху проекта. Получение конструктивной обратной связи побудит разработчиков учиться на своих ошибках и расширять свои возможности. Рецензенты могут оставлять комментарии с префиксом «Nit:» (от «nitpicking» - придирки). Это означает, что такие вещи не обязательно должны исправляться, а имеют образовательную цель и помогают разработчикам постоянно совершенствовать свои навыки. Например:
Если цели процесса обзора кода определены заранее, гораздо проще измерить эффективность кода и решить, приносит ли проверка пользу и помогает ли достичь ожидаемых результатов. Настройка внешних и внутренних показателей позволяет разработчикам улучшить качество кода. Примерами внешних показателей могут быть «уменьшение процента дефектов, сообщаемых конечными пользователями» или «уменьшение количества дефектов, обнаруженных до запуска продукта».
Внутренние показатели включают:
- Скорость проверки.
- Дефектность: среднее количество ошибок, обнаруженных за один сеанс.
- Плотность дефектов: среднее количество ошибок на строку кода.
7. Комментируйте код для рецензента
Комментарии предоставляет информацию о том, что пытается выполнить каждая строка или раздел кода. Они также могут показать рецензенту, какие изменения были внесены, какие методы модификации кода использовались и почему это было полезно. Эта практика способствует более глубокому пониманию кода рецензентом и упрощает общий процесс проверки кода. Например:
Разработчик – человек, поэтому может упустить из виду некоторые аспекты кода. Чек-лист сделает процесс проверки более последовательным, поскольку будет постоянно напоминать о том, что следует проверять. Он особенно полезен для рецензента, поскольку помогает проводить проверку по конкретным критериям. Однако существует и такое понятие, как личный чек-лист. Если автор кода знает о своих типичных ошибках и недостатках в работе, он может составить чек-лист, чтобы постоянно улучшать качество своего кода. Кроме того, чек-листы проверки кода очень важны для выявления упущений, которые труднее всего проверять, потому что сложно обнаружить отсутствие чего-либо.
Вот некоторые вопросы для чек-листа:
- Легко ли понять код?
- Соответствует ли форматирование кода соглашению по проекту?
- Достаточно ли модульная структура кода?
- Соответствует ли выбранное решение требованиям?
- Проверена ли вся логика и все ошибки?
- Есть ли проблемы в безопасности?
- Как дела с производительностью? (Есть ли очевидные моменты для оптимизации?)
- Весь ли код покрыт тестами?
- Насколько эффективно и информативно описание пул реквеста?
9. Включайте всех
Чем больше будет глаз, тем легче найти ошибку. Люди, как правило, работают лучше, если знают, что их работа будет проверена. Неважно, какой уровень квалификации у программиста - каждый должен участвовать в процессе обзора кода. Младшие разработчики могут обучаться новым или альтернативным методам выполнения чего-либо у своих старших коллег, а старшие могут совершенствовать свои навыки программирования, написав код, понятный и читаемый для всех.
Источник: https://dzone.com/articles/9-best-practices-for-effective-code-review
Лучшие Практики для Эффективных Обзоров Кода. Окончание
Начало
5. Давайте конструктивную обратную связь
Взаимная проверка кода направлена на повышение производительности команды, а не на разжигание конкуренции между автором кода и рецензентом. В любом случае код необходимо проверять. И если разработчики воспринимают это как процесс обучения, а не критику своей работы, это способствует общему успеху проекта. Получение конструктивной обратной связи побудит разработчиков учиться на своих ошибках и расширять свои возможности. Рецензенты могут оставлять комментарии с префиксом «Nit:» (от «nitpicking» - придирки). Это означает, что такие вещи не обязательно должны исправляться, а имеют образовательную цель и помогают разработчикам постоянно совершенствовать свои навыки. Например:
var file = app != null && !string.IsNullOrEmpty(app.FilePath);6. Установка целей и сбор метрик
// Nit: может быть заменено на
// !string.IsNullOrEmpty(app?.FilePath);
Если цели процесса обзора кода определены заранее, гораздо проще измерить эффективность кода и решить, приносит ли проверка пользу и помогает ли достичь ожидаемых результатов. Настройка внешних и внутренних показателей позволяет разработчикам улучшить качество кода. Примерами внешних показателей могут быть «уменьшение процента дефектов, сообщаемых конечными пользователями» или «уменьшение количества дефектов, обнаруженных до запуска продукта».
Внутренние показатели включают:
- Скорость проверки.
- Дефектность: среднее количество ошибок, обнаруженных за один сеанс.
- Плотность дефектов: среднее количество ошибок на строку кода.
7. Комментируйте код для рецензента
Комментарии предоставляет информацию о том, что пытается выполнить каждая строка или раздел кода. Они также могут показать рецензенту, какие изменения были внесены, какие методы модификации кода использовались и почему это было полезно. Эта практика способствует более глубокому пониманию кода рецензентом и упрощает общий процесс проверки кода. Например:
// Начинаем с 1, чтобы 0 был недопустимым8. Используйте чек-листы
// и это можно было проверять при передаче параметра извне
public enum SupplierStatsType {
All = 1, General = 2, Custom = 3
}
Разработчик – человек, поэтому может упустить из виду некоторые аспекты кода. Чек-лист сделает процесс проверки более последовательным, поскольку будет постоянно напоминать о том, что следует проверять. Он особенно полезен для рецензента, поскольку помогает проводить проверку по конкретным критериям. Однако существует и такое понятие, как личный чек-лист. Если автор кода знает о своих типичных ошибках и недостатках в работе, он может составить чек-лист, чтобы постоянно улучшать качество своего кода. Кроме того, чек-листы проверки кода очень важны для выявления упущений, которые труднее всего проверять, потому что сложно обнаружить отсутствие чего-либо.
Вот некоторые вопросы для чек-листа:
- Легко ли понять код?
- Соответствует ли форматирование кода соглашению по проекту?
- Достаточно ли модульная структура кода?
- Соответствует ли выбранное решение требованиям?
- Проверена ли вся логика и все ошибки?
- Есть ли проблемы в безопасности?
- Как дела с производительностью? (Есть ли очевидные моменты для оптимизации?)
- Весь ли код покрыт тестами?
- Насколько эффективно и информативно описание пул реквеста?
9. Включайте всех
Чем больше будет глаз, тем легче найти ошибку. Люди, как правило, работают лучше, если знают, что их работа будет проверена. Неважно, какой уровень квалификации у программиста - каждый должен участвовать в процессе обзора кода. Младшие разработчики могут обучаться новым или альтернативным методам выполнения чего-либо у своих старших коллег, а старшие могут совершенствовать свои навыки программирования, написав код, понятный и читаемый для всех.
Источник: https://dzone.com/articles/9-best-practices-for-effective-code-review
День девятьсот семьдесят девятый. #Оффтоп #CodeReview
Обзоры Кода. Передовой Опыт. Начало
Обзоры кода - это процесс, в котором один или несколько разработчиков систематически проверяют код, написанный другим разработчиком, для обнаружения дефектов и улучшения кода. Обзоры кода чаще выполняются опытными разработчиками, которые учитывают различные аспекты, включая качество и безопасность кода. Кроме того, они способствуют обмену знаниями, лучшей кооперации, формированию культуры взаимных проверок, укреплению уверенности команды в коде, над которым они работают.
Затраты на обзор кода
Помимо анализа кода, есть ещё два хорошо известных метода, использующихся в процессе разработки.
- Написание тестов для частой и автоматической проверки нового и отредактированного кода.
- Использование инструментов, которые проверяют код, на предмет «запахов» и ошибок.
В отличие от тестов и инструментов анализа, обзор кода, выполняемый человеком, может рассматриваться как попытка учуять запах дыма. По аналогии с дымовым тестированием (Smoke testing). Это значит, что вручную выполняется поверхностная проверка определённого функционала на наличие явных ошибок. При изменении кода его нужно проводить снова, точно так же, как обзор кода. По этой причине обзор кода - дорогостоящая задача, поскольку требует человеческих ресурсов и должна повторяться снова и снова после каждого изменения кода.
Преимущества обзоров кода
Стоимость обзоров кода высока. С другой стороны, преимущества довольно ощутимы:
1. Обучение
При обзорах кода младшие программисты получают советы от старших относительно их собственного кода. Нет лучшего способа изучить правильные методы и продвигать принципы и требования корпоративного стиля.
2. Коммуникация
При обзорах кода программисты непременно общаются друг с другом и делятся мнениями. Это способствует развитию дружеских отношений и улучшает сплочённость команды.
3. Распространение знаний
Каждая команда должна бороться с единоличным владением кодом, т.е. когда один человек владеет какой-то кодовой базой или компонентом. Владение кодом вызывает трения и стресс как для владельца кода, так и для его/её коллег. Владелец больше не учится у других и может лениться, поскольку его работа не оценивается другими. С другой стороны, другие могут столкнуться с серьёзной проблемой, когда владелец отсутствует или покидает команду. Проверка кода - лучший способ распространения знаний и предотвращения владения кодом.
4. Мотивация к прогрессу
Очевидно, что, если вы знаете, что ваш код будет проверяться коллегами, вы уделите ему больше внимания. Вы потратите время на то, чтобы правильно назвать идентификаторы, написать тесты, ввести хорошо продуманные абстракции и тщательно использовать корпоративные шаблоны.
5. Лучший код
Поскольку в основе анализа кода лежат интеллект, опыт и внимание разработчика, он может помочь на ранней стадии обнаружить дефекты, которые нельзя обнаружить с помощью тестирования и автоматизированных инструментов.
При обзорах кода не только улучшается результирующий код, но и прогрессирует каждый член команды как разработчик. Такие чисто человеческие преимущества не могут быть получены с помощью другой практики. Однако они могут стать решающим фактором между успешным проектом и провалом. Таким образом, обзоры кода, вне зависимости от их стоимости могут стоить того.
Продолжение следует…
Источник: https://blog.ndepend.com/what-is-code-review-guidelines-best-practices/
Обзоры Кода. Передовой Опыт. Начало
Обзоры кода - это процесс, в котором один или несколько разработчиков систематически проверяют код, написанный другим разработчиком, для обнаружения дефектов и улучшения кода. Обзоры кода чаще выполняются опытными разработчиками, которые учитывают различные аспекты, включая качество и безопасность кода. Кроме того, они способствуют обмену знаниями, лучшей кооперации, формированию культуры взаимных проверок, укреплению уверенности команды в коде, над которым они работают.
Затраты на обзор кода
Помимо анализа кода, есть ещё два хорошо известных метода, использующихся в процессе разработки.
- Написание тестов для частой и автоматической проверки нового и отредактированного кода.
- Использование инструментов, которые проверяют код, на предмет «запахов» и ошибок.
В отличие от тестов и инструментов анализа, обзор кода, выполняемый человеком, может рассматриваться как попытка учуять запах дыма. По аналогии с дымовым тестированием (Smoke testing). Это значит, что вручную выполняется поверхностная проверка определённого функционала на наличие явных ошибок. При изменении кода его нужно проводить снова, точно так же, как обзор кода. По этой причине обзор кода - дорогостоящая задача, поскольку требует человеческих ресурсов и должна повторяться снова и снова после каждого изменения кода.
Преимущества обзоров кода
Стоимость обзоров кода высока. С другой стороны, преимущества довольно ощутимы:
1. Обучение
При обзорах кода младшие программисты получают советы от старших относительно их собственного кода. Нет лучшего способа изучить правильные методы и продвигать принципы и требования корпоративного стиля.
2. Коммуникация
При обзорах кода программисты непременно общаются друг с другом и делятся мнениями. Это способствует развитию дружеских отношений и улучшает сплочённость команды.
3. Распространение знаний
Каждая команда должна бороться с единоличным владением кодом, т.е. когда один человек владеет какой-то кодовой базой или компонентом. Владение кодом вызывает трения и стресс как для владельца кода, так и для его/её коллег. Владелец больше не учится у других и может лениться, поскольку его работа не оценивается другими. С другой стороны, другие могут столкнуться с серьёзной проблемой, когда владелец отсутствует или покидает команду. Проверка кода - лучший способ распространения знаний и предотвращения владения кодом.
4. Мотивация к прогрессу
Очевидно, что, если вы знаете, что ваш код будет проверяться коллегами, вы уделите ему больше внимания. Вы потратите время на то, чтобы правильно назвать идентификаторы, написать тесты, ввести хорошо продуманные абстракции и тщательно использовать корпоративные шаблоны.
5. Лучший код
Поскольку в основе анализа кода лежат интеллект, опыт и внимание разработчика, он может помочь на ранней стадии обнаружить дефекты, которые нельзя обнаружить с помощью тестирования и автоматизированных инструментов.
При обзорах кода не только улучшается результирующий код, но и прогрессирует каждый член команды как разработчик. Такие чисто человеческие преимущества не могут быть получены с помощью другой практики. Однако они могут стать решающим фактором между успешным проектом и провалом. Таким образом, обзоры кода, вне зависимости от их стоимости могут стоить того.
Продолжение следует…
Источник: https://blog.ndepend.com/what-is-code-review-guidelines-best-practices/
👍1
День девятьсот восьмидесятый. #Оффтоп #CodeReview
Обзоры Кода. Передовой Опыт. Продолжение
Начало
Как проводить обзор кода
1. Уведомление о том, что код готов к обзору
Часто обзор кода проводится неформально. Когда разработчик завершает какую-то часть кодирования, он уведомляет одного или нескольких членов команды, чтобы они проверили код, когда смогут. Неплохо для начала, но такие обзоры не являются систематическими, плохо отслеживаются и не поддаются измерению.
2. Обзор «через плечо»
В отличие от предыдущего способа, обзор «через плечо» предполагает синхронную проверку. Он заключается в том, чтобы попросить одного или нескольких разработчиков присоединиться, чтобы представить им сделанную работу и получить комментарии. В идеале коллега присоединяется физически, но в настоящее время многие разработчики работают из дома, и такой обзор может проводиться удалённо. Обзор «через плечо» страдает теми же недостатками неформальности, что и предыдущий способ. Однако он побуждает разработчика участвовать в реальном обсуждении, а не просто отправить комментарии по почте когда-нибудь потом, что лучше для командной работы.
3. Парное программирование
Парное программирование - это метод гибкой разработки программного обеспечения, пришедший из XP (Extreme Programming). Парное программирование предполагает команду из двух разработчиков, работающих вместе на одном компьютере. Они объединяют свои усилия для написания кода и тестов. Это является одной из форм проверки кода, поскольку клавиатура одна: один проверяет код, написанный другим.
Парное программирование имеет несколько преимуществ. Это отличный способ наставить младшего разработчика и как можно раньше выявить некоторые дефекты.
С другой стороны, разработчики часто достигают пика своей продуктивности, когда они одни, «в потоке», и когда их не отвлекают. Таким образом, систематическое парное программирование снижает продуктивность и снижает энтузиазм разработчиков. Код, написанный одним разработчиком «в потоке», все равно может быть пересмотрен и улучшен позже другими.
4. Инструменты для автоматической проверки кода
Инструменты автоматической проверки кода помогают серьёзно улучшить процесс обзора кода. С помощью инструментов обзоры могут стать систематическими. Их можно отследить, и можно сделать вывод о том, как улучшить процесс на основании некоторых показателей. Пул-реквесты в Github сейчас популярный способ проведения большинства проверок. Существуют также более сложные инструменты, такие как SmartBear Collaborator с широким спектром поддерживаемых систем управления версиями.
Однако обратная сторона обзора кода - его высокая стоимость, поскольку он требует больших человеческих усилий. Вот почему команда должна бороться за автоматизацию большинства проверок, чтобы максимально снизить человеческое участие. Другой инструмент – NDepend - анализирует многие аспекты кода, такие как именование, сложность, дизайн, запахи кода, покрытие кода тестами и т.п. При этом он создаёт моментальные снимки кода. Два моментальных снимка можно сравнить между собой. Инструмент также поддерживает LINQ-подобные запросы для оценки качества кода. Например, перед любой проверкой кода человеком, можно внедрить правило проверки на сложность методов с помощью запроса ниже:
Окончание следует…
Источник: https://blog.ndepend.com/what-is-code-review-guidelines-best-practices/
Обзоры Кода. Передовой Опыт. Продолжение
Начало
Как проводить обзор кода
1. Уведомление о том, что код готов к обзору
Часто обзор кода проводится неформально. Когда разработчик завершает какую-то часть кодирования, он уведомляет одного или нескольких членов команды, чтобы они проверили код, когда смогут. Неплохо для начала, но такие обзоры не являются систематическими, плохо отслеживаются и не поддаются измерению.
2. Обзор «через плечо»
В отличие от предыдущего способа, обзор «через плечо» предполагает синхронную проверку. Он заключается в том, чтобы попросить одного или нескольких разработчиков присоединиться, чтобы представить им сделанную работу и получить комментарии. В идеале коллега присоединяется физически, но в настоящее время многие разработчики работают из дома, и такой обзор может проводиться удалённо. Обзор «через плечо» страдает теми же недостатками неформальности, что и предыдущий способ. Однако он побуждает разработчика участвовать в реальном обсуждении, а не просто отправить комментарии по почте когда-нибудь потом, что лучше для командной работы.
3. Парное программирование
Парное программирование - это метод гибкой разработки программного обеспечения, пришедший из XP (Extreme Programming). Парное программирование предполагает команду из двух разработчиков, работающих вместе на одном компьютере. Они объединяют свои усилия для написания кода и тестов. Это является одной из форм проверки кода, поскольку клавиатура одна: один проверяет код, написанный другим.
Парное программирование имеет несколько преимуществ. Это отличный способ наставить младшего разработчика и как можно раньше выявить некоторые дефекты.
С другой стороны, разработчики часто достигают пика своей продуктивности, когда они одни, «в потоке», и когда их не отвлекают. Таким образом, систематическое парное программирование снижает продуктивность и снижает энтузиазм разработчиков. Код, написанный одним разработчиком «в потоке», все равно может быть пересмотрен и улучшен позже другими.
4. Инструменты для автоматической проверки кода
Инструменты автоматической проверки кода помогают серьёзно улучшить процесс обзора кода. С помощью инструментов обзоры могут стать систематическими. Их можно отследить, и можно сделать вывод о том, как улучшить процесс на основании некоторых показателей. Пул-реквесты в Github сейчас популярный способ проведения большинства проверок. Существуют также более сложные инструменты, такие как SmartBear Collaborator с широким спектром поддерживаемых систем управления версиями.
Однако обратная сторона обзора кода - его высокая стоимость, поскольку он требует больших человеческих усилий. Вот почему команда должна бороться за автоматизацию большинства проверок, чтобы максимально снизить человеческое участие. Другой инструмент – NDepend - анализирует многие аспекты кода, такие как именование, сложность, дизайн, запахи кода, покрытие кода тестами и т.п. При этом он создаёт моментальные снимки кода. Два моментальных снимка можно сравнить между собой. Инструмент также поддерживает LINQ-подобные запросы для оценки качества кода. Например, перед любой проверкой кода человеком, можно внедрить правило проверки на сложность методов с помощью запроса ниже:
// <Name>Avoid complex methods</Name>Строка
warnif count > 0
from m in JustMyCode.Methods
where m.CyclomaticComplexity > 20
select new { m, m.CyclomaticComplexity, m.NbLinesOfCode }
warnif count > 0 автоматически переводит запрос в правило, которое выдаст предупреждение компилятора.Окончание следует…
Источник: https://blog.ndepend.com/what-is-code-review-guidelines-best-practices/
День девятьсот восемьдесят первый. #Оффтоп #CodeReview
Обзоры Кода. Передовой Опыт. Окончание
Начало
Продолжение
На что обращать внимание при обзоре кода
Многие аспекты проверки кода можно автоматизировать, но человеческие навыки и опыт остаются критичными для обнаружения важных улучшений:
1. Ошибки требований
Разработчик мог неправильно понять некоторые требования. Его код может быть протестирован на 100%, но, если и код, и написанные тесты основаны на неправильных предположениях, задача не может считаться выполненной.
2. Изменения пользовательского интерфейса
Создание правильного UI, который сделает пользователей продуктивными, - одна из самых сложных задач разработки. Проверка кода и проверка UI специалистами команды являются обязательными, чтобы убедиться, что продукт развивается в правильном направлении.
3. Трудно находимые ошибки
Ошибки, связанные с параллельной обработкой (взаимоблокировки, состояния гонки и т.п.), трудно обнаружить, трудно воспроизвести и трудно исправить. Младшие разработчики часто их допускают, даже не подозревая, что они могут произойти. При обзоре кода опытный программист сможет оценить, возможно ли возникновение ошибки. Например, он проверит изменение общего состояния и чистоту метода. Также могут быть обнаружены некоторые другие сложные ошибки, включая утечку памяти и проблемы производительности, вроде проблемы N+1 запроса.
4. Уязвимости
Существует широкий спектр потенциальных ловушек безопасности, требующих специальных знаний. Некоторые инструменты, такие как Semmle, могут автоматически обнаруживать многие из этих подводных камней. Но если безопасность вас беспокоит (а она должна беспокоить), необходимы регулярные обзоры кода, проводимые экспертами по безопасности.
5. Именование
Для обеспечения соблюдения простых требований к именованию могут быть написаны автоматические правила. Также инструментальные средства могут заставить использовать предопределённую терминологию основного домена. Кроме того, правильное именование особенно важно для публичных идентификаторов API. Вот почему требуется тщательный анализ именования человеком.
6. Тестирование
Тестирование можно измерить и в значительной степени автоматизировать. Но коэффициента покрытия кода и количества пройденных тестов недостаточно. Человек должен просмотреть тесты, чтобы убедиться в правильности установленных условий и в том, что тесты не слишком сложны.
7. Последовательность
Часто молодые участники команды заново изобретают колесо, потому что не знакомы с общекорпоративными шаблонами и библиотеками. Некоторые автоматические правила могут быть написаны для принудительного использования определённых классов в определённых ситуациях. Но обзоры кода представляют собой отличный способ рассказать о культуре и базе знаний компании.
8. Комментарий
Комментарии должны быть написаны тщательно на правильном человеческом языке, чтобы объяснить, почему этот код написан и почему написан именно таким образом. Например, когда какой-то нетривиальный код адаптируется из ответа со Stackoverflow, стоит указать URL ответа и контекст. С другой стороны, код должен быть достаточно читабельным, чтобы не нужно было комментариев, объясняющих, что он делает.
9. Документация
Инструменты могут легко обнаружить недостающую документацию. IDE, вроде Visual Studio, может легко сгенерировать скелет класса или документацию метода. Но документация пишется человеком и для человека. Чтобы она была действительно информативной, необходима надлежащая проверка со стороны человека. Мы, разработчики, регулярно разочаровываемся в поверхностной и устаревшей документации, которая на самом деле не объясняет, зачем нужен API, как его следует использовать и чего от него ожидать. Правильная документация - отличный способ снизить затраты на поддержку и снизить разочарование пользователей.
Источник: https://blog.ndepend.com/what-is-code-review-guidelines-best-practices/
Обзоры Кода. Передовой Опыт. Окончание
Начало
Продолжение
На что обращать внимание при обзоре кода
Многие аспекты проверки кода можно автоматизировать, но человеческие навыки и опыт остаются критичными для обнаружения важных улучшений:
1. Ошибки требований
Разработчик мог неправильно понять некоторые требования. Его код может быть протестирован на 100%, но, если и код, и написанные тесты основаны на неправильных предположениях, задача не может считаться выполненной.
2. Изменения пользовательского интерфейса
Создание правильного UI, который сделает пользователей продуктивными, - одна из самых сложных задач разработки. Проверка кода и проверка UI специалистами команды являются обязательными, чтобы убедиться, что продукт развивается в правильном направлении.
3. Трудно находимые ошибки
Ошибки, связанные с параллельной обработкой (взаимоблокировки, состояния гонки и т.п.), трудно обнаружить, трудно воспроизвести и трудно исправить. Младшие разработчики часто их допускают, даже не подозревая, что они могут произойти. При обзоре кода опытный программист сможет оценить, возможно ли возникновение ошибки. Например, он проверит изменение общего состояния и чистоту метода. Также могут быть обнаружены некоторые другие сложные ошибки, включая утечку памяти и проблемы производительности, вроде проблемы N+1 запроса.
4. Уязвимости
Существует широкий спектр потенциальных ловушек безопасности, требующих специальных знаний. Некоторые инструменты, такие как Semmle, могут автоматически обнаруживать многие из этих подводных камней. Но если безопасность вас беспокоит (а она должна беспокоить), необходимы регулярные обзоры кода, проводимые экспертами по безопасности.
5. Именование
Для обеспечения соблюдения простых требований к именованию могут быть написаны автоматические правила. Также инструментальные средства могут заставить использовать предопределённую терминологию основного домена. Кроме того, правильное именование особенно важно для публичных идентификаторов API. Вот почему требуется тщательный анализ именования человеком.
6. Тестирование
Тестирование можно измерить и в значительной степени автоматизировать. Но коэффициента покрытия кода и количества пройденных тестов недостаточно. Человек должен просмотреть тесты, чтобы убедиться в правильности установленных условий и в том, что тесты не слишком сложны.
7. Последовательность
Часто молодые участники команды заново изобретают колесо, потому что не знакомы с общекорпоративными шаблонами и библиотеками. Некоторые автоматические правила могут быть написаны для принудительного использования определённых классов в определённых ситуациях. Но обзоры кода представляют собой отличный способ рассказать о культуре и базе знаний компании.
8. Комментарий
Комментарии должны быть написаны тщательно на правильном человеческом языке, чтобы объяснить, почему этот код написан и почему написан именно таким образом. Например, когда какой-то нетривиальный код адаптируется из ответа со Stackoverflow, стоит указать URL ответа и контекст. С другой стороны, код должен быть достаточно читабельным, чтобы не нужно было комментариев, объясняющих, что он делает.
9. Документация
Инструменты могут легко обнаружить недостающую документацию. IDE, вроде Visual Studio, может легко сгенерировать скелет класса или документацию метода. Но документация пишется человеком и для человека. Чтобы она была действительно информативной, необходима надлежащая проверка со стороны человека. Мы, разработчики, регулярно разочаровываемся в поверхностной и устаревшей документации, которая на самом деле не объясняет, зачем нужен API, как его следует использовать и чего от него ожидать. Правильная документация - отличный способ снизить затраты на поддержку и снизить разочарование пользователей.
Источник: https://blog.ndepend.com/what-is-code-review-guidelines-best-practices/
День 1092. #CodeReview
10 Советов по Написанию Эффективных Обзоров Кода. Начало
Существует несколько хороших практик, которые рецензент может использовать, чтобы сделать процесс рецензирования менее скучным и более ясным. Это выигрыш для всех, потому что:
- автор будет более четко понимать ваши отзывы, что приведёт к меньшему количеству итераций обзоров кода;
- вы будете давать автору советы и замечания, которые повлияют на его подход к кодовой базе в целом, чтобы в следующий раз было меньше «ошибок».
Вот несколько советов и практических правил относительно подхода к процессу рецензии.
1. Всегда сообщайте «почему»
Рассмотрим некоторые типичные комментарии из обзора:
- «неправильное имя функции»,
- «этого не должно быть здесь»,
- «думаю, это может сломаться».
По этим комментариям автор кода может только предположить, что не так с его кодом. Но может прийти к неправильному выводу о том, почему он не верен, и сделать неправильное исправление. Это приведёт к дополнительной итерации обзора.
Вот пример хорошего комментария:
«Это имя функции не идеально; оно должно начинаться с глагола действия, и в этом случае иметь указание аргумента, типа '...ByUserId'. Подробнее см. документацию по стилю кода.»
Да, вы написали кучу слов, зато ясно объяснили автору, что не так, и как следует поступать в будущем.
2. Будьте тщательны
Автором кода может быть самый высокопоставленный человек в вашей команде, знающий все тонкости кодовой базы, или новичок, который отправляет свой первый код на обзор. Это не должно влиять на качество или тщательность вашей проверки, и вы не должны давать старшему сотруднику поблажки только потому, что доверяете его работе.
Обзоры кода — это не только обеспечение качества и структуры кода, но и поиск граничных случаев или ошибок, которые автор мог не заметить, либо даже просто случайных опечаток.
Признайтесь, это случается с лучшими из нас. Выявление ошибки до того, как она будет отправлена в производственный код, всегда более эффективно, чем обнаружение её в рабочем коде, создание багрепорта, поиск причины, исправление проблемы и отправка кода на повторную проверку.
3. Не выдавайте конечный результат
Как рецензент изменений кода, вы не должны исправлять его или придумывать решение, когда обнаружите проблему. Да, вы можете помочь или предложить свою идею, но это не значит давать полное решение проблемы. Следующий комментарий мало чему научит автора:
«Этот метод не совсем подходит, он должен быть примерно таким:
Скорее всего, автор скопирует и вставит его себе, не задумываясь. И в дальнейшем не будет сильно беспокоиться о качестве своего кода, если будет знать, что вы за него всё исправите.
Правильно в этом случае было бы описать, как должен выглядеть метод, объяснить, почему код не сработает, и как бы вы подошли к решению проблемы. Иногда допустим псевдокод.
4. Не откладывайте обзор
Очень важно не блокировать работу друг друга. Переключение контекста — непростая задача для разработчика. И в ожидании обзора кода по одной из своих задач автору придётся переключиться на другую, и переключаться туда и обратно, по мере получения комментариев и ответа на них. Это в любом случае произойдет, даже если проверка пройдёт очень быстро. Однако, чем дольше затянется обзор, тем больше таких переключений будет происходить.
Кроме того, вы можете и фактически блокировать чью-то работу. Т.е. люди не смогут продолжать работу, пока эта функция не будет завершена и изменения кода не будут объединены. Всё это неэффективно и раздражает обе стороны.
Чтобы убедиться, что такого не произойдёт, всегда полезно отдавать приоритет проверкам кода в своем расписании. Конечно, у вас могут быть более срочные задачи, но вы обязаны найти правильный баланс между собственной работой и обзорами.
Окончание следует…
Источник: https://betterprogramming.pub/10-tips-to-write-effective-code-reviews-c25c25aa22c5
10 Советов по Написанию Эффективных Обзоров Кода. Начало
Существует несколько хороших практик, которые рецензент может использовать, чтобы сделать процесс рецензирования менее скучным и более ясным. Это выигрыш для всех, потому что:
- автор будет более четко понимать ваши отзывы, что приведёт к меньшему количеству итераций обзоров кода;
- вы будете давать автору советы и замечания, которые повлияют на его подход к кодовой базе в целом, чтобы в следующий раз было меньше «ошибок».
Вот несколько советов и практических правил относительно подхода к процессу рецензии.
1. Всегда сообщайте «почему»
Рассмотрим некоторые типичные комментарии из обзора:
- «неправильное имя функции»,
- «этого не должно быть здесь»,
- «думаю, это может сломаться».
По этим комментариям автор кода может только предположить, что не так с его кодом. Но может прийти к неправильному выводу о том, почему он не верен, и сделать неправильное исправление. Это приведёт к дополнительной итерации обзора.
Вот пример хорошего комментария:
«Это имя функции не идеально; оно должно начинаться с глагола действия, и в этом случае иметь указание аргумента, типа '...ByUserId'. Подробнее см. документацию по стилю кода.»
Да, вы написали кучу слов, зато ясно объяснили автору, что не так, и как следует поступать в будущем.
2. Будьте тщательны
Автором кода может быть самый высокопоставленный человек в вашей команде, знающий все тонкости кодовой базы, или новичок, который отправляет свой первый код на обзор. Это не должно влиять на качество или тщательность вашей проверки, и вы не должны давать старшему сотруднику поблажки только потому, что доверяете его работе.
Обзоры кода — это не только обеспечение качества и структуры кода, но и поиск граничных случаев или ошибок, которые автор мог не заметить, либо даже просто случайных опечаток.
Признайтесь, это случается с лучшими из нас. Выявление ошибки до того, как она будет отправлена в производственный код, всегда более эффективно, чем обнаружение её в рабочем коде, создание багрепорта, поиск причины, исправление проблемы и отправка кода на повторную проверку.
3. Не выдавайте конечный результат
Как рецензент изменений кода, вы не должны исправлять его или придумывать решение, когда обнаружите проблему. Да, вы можете помочь или предложить свою идею, но это не значит давать полное решение проблемы. Следующий комментарий мало чему научит автора:
«Этот метод не совсем подходит, он должен быть примерно таким:
<кусок кода>»
Скорее всего, автор скопирует и вставит его себе, не задумываясь. И в дальнейшем не будет сильно беспокоиться о качестве своего кода, если будет знать, что вы за него всё исправите.
Правильно в этом случае было бы описать, как должен выглядеть метод, объяснить, почему код не сработает, и как бы вы подошли к решению проблемы. Иногда допустим псевдокод.
4. Не откладывайте обзор
Очень важно не блокировать работу друг друга. Переключение контекста — непростая задача для разработчика. И в ожидании обзора кода по одной из своих задач автору придётся переключиться на другую, и переключаться туда и обратно, по мере получения комментариев и ответа на них. Это в любом случае произойдет, даже если проверка пройдёт очень быстро. Однако, чем дольше затянется обзор, тем больше таких переключений будет происходить.
Кроме того, вы можете и фактически блокировать чью-то работу. Т.е. люди не смогут продолжать работу, пока эта функция не будет завершена и изменения кода не будут объединены. Всё это неэффективно и раздражает обе стороны.
Чтобы убедиться, что такого не произойдёт, всегда полезно отдавать приоритет проверкам кода в своем расписании. Конечно, у вас могут быть более срочные задачи, но вы обязаны найти правильный баланс между собственной работой и обзорами.
Окончание следует…
Источник: https://betterprogramming.pub/10-tips-to-write-effective-code-reviews-c25c25aa22c5
👍6
День 1093. #CodeReview
10 Советов по Написанию Эффективных Обзоров Кода. Окончание
Начало
5. Следуйте рекомендациям
Если ваша команда достаточно большая, у вас наверняка есть некоторые рекомендации по написанию кода проекта: общие подходы к организации кода, соглашения об именах и т.п. Если вы активно пишете код и просматриваете код других, вы, вероятно, привыкли к ним. Однако полезно возвращаться к рекомендациям и пробегать их глазами каждые пару недель или каждый месяц. Вы будете удивлены, увидев, сколько моментов вы забыли или на которые не обращали внимания в обзорах.
Если у вашей команды нет этих правил, было бы неплохо написать их во время очередной проверки кода. Такой список будет служить единственным источником правды в вашей команде, гарантируя, что у всех авторов кода и рецензентов есть ресурс, на который можно обратить внимание при написании/обновлении/чтении кода.
6. Хвалите хороший код
Проверка кода не всегда связана с криткой. Иногда вы будете натыкаться на код, который заставит вас отдать должное автору. Кусок логики, очень эффективная оптимизация запросов или блестящий UX. Сообщите об этом.
Можно оставить простой комментарий, типа, «неплохо!» или более длинный с рассказом, что вам в нём понравилось. В любом случае, человек почувствует, что его ценят, и это определенно улучшит командную работу. А если остальная часть кода не так хороша, автору будет не так обидно. Кроме того, подтверждение качества куска кода побудит автора пытаться создавать больше подобного кода в будущем или выполнять аналогичные действия для других проблем.
7. Будьте скромны и позитивны
Неинформативные и грубые комментарии (если у вас не задался день) просто оскорбительны, обескураживают и не несут никакой ценности. Полезно быть дружелюбным в комментариях, уважать время и труд другого человека и предполагать, что он старался изо всех сил при написании кода. Нет абсолютно никакой пользы в хвастовстве, унижении или гневе в код-ревью.
8. Ссылайтесь на ресурсы
Если есть известный вам ресурс, который поможет автору кода решить проблему, дайте ссылку на него в своём комментарии. Чаще всего автор оценит комментарий, и может даже станет регулярно использовать этот ресурс в своей работе.
Возможно, ещё более важно указать на ресурс из вашей кодовой базы: подобная логика или компонент, который уже был реализован кем-то другим в прошлом, может стать отличным руководством для автора, а он может не знать об этом конкретном разделе кодовой базы, если не работал с ним раньше.
9. Это не вы, это они
При чтении кода важно, чтобы вы могли легко его понимать. Если какая-то часть кода кажется непонятной, это не значит, что вы невнимательно прочитали код. Это означает, что код недостаточно ясен.
Если у вас есть проблемы с пониманием того, что делает этот фрагмент, другим разработчикам, вероятно, будет трудно понять его в будущем, когда им понадобится изменить эту часть кода. Когда вы обнаружите такой код, не стесняйтесь сообщить об этом. И не просто просите автора объяснить его, попросите переписать его. Если нельзя написать более понятно, хотя бы попросите автора добавить комментарии.
10. Ваше мнение не всегда правильно
Обычно существует более одного способа добиться цели. Читая фрагмент кода, вы, вероятно, представите другие способы сделать это и почувствуете желание предложить это в комментарии как лучшее решение. Иногда нужно спросить себя: действительно ли оно лучше или способ автора тоже хорош?
Если нет явного преимущества в сложности или удобочитаемости кода, подумайте дважды, прежде чем предлагать переписать его. Перечитайте код и убедитесь, что он соответствует принятым в вашей команде соглашениям, хорошо выполняет свою работу, и сравните его с альтернативным вариантом, чтобы увидеть, как это повлияет на качество кода. Если способ автора приемлем, но вы по-прежнему считаете, что ваш вариант лучше, напишите его как предложение, а не как обязательное изменение.
Источник: https://betterprogramming.pub/10-tips-to-write-effective-code-reviews-c25c25aa22c5
10 Советов по Написанию Эффективных Обзоров Кода. Окончание
Начало
5. Следуйте рекомендациям
Если ваша команда достаточно большая, у вас наверняка есть некоторые рекомендации по написанию кода проекта: общие подходы к организации кода, соглашения об именах и т.п. Если вы активно пишете код и просматриваете код других, вы, вероятно, привыкли к ним. Однако полезно возвращаться к рекомендациям и пробегать их глазами каждые пару недель или каждый месяц. Вы будете удивлены, увидев, сколько моментов вы забыли или на которые не обращали внимания в обзорах.
Если у вашей команды нет этих правил, было бы неплохо написать их во время очередной проверки кода. Такой список будет служить единственным источником правды в вашей команде, гарантируя, что у всех авторов кода и рецензентов есть ресурс, на который можно обратить внимание при написании/обновлении/чтении кода.
6. Хвалите хороший код
Проверка кода не всегда связана с криткой. Иногда вы будете натыкаться на код, который заставит вас отдать должное автору. Кусок логики, очень эффективная оптимизация запросов или блестящий UX. Сообщите об этом.
Можно оставить простой комментарий, типа, «неплохо!» или более длинный с рассказом, что вам в нём понравилось. В любом случае, человек почувствует, что его ценят, и это определенно улучшит командную работу. А если остальная часть кода не так хороша, автору будет не так обидно. Кроме того, подтверждение качества куска кода побудит автора пытаться создавать больше подобного кода в будущем или выполнять аналогичные действия для других проблем.
7. Будьте скромны и позитивны
Неинформативные и грубые комментарии (если у вас не задался день) просто оскорбительны, обескураживают и не несут никакой ценности. Полезно быть дружелюбным в комментариях, уважать время и труд другого человека и предполагать, что он старался изо всех сил при написании кода. Нет абсолютно никакой пользы в хвастовстве, унижении или гневе в код-ревью.
8. Ссылайтесь на ресурсы
Если есть известный вам ресурс, который поможет автору кода решить проблему, дайте ссылку на него в своём комментарии. Чаще всего автор оценит комментарий, и может даже станет регулярно использовать этот ресурс в своей работе.
Возможно, ещё более важно указать на ресурс из вашей кодовой базы: подобная логика или компонент, который уже был реализован кем-то другим в прошлом, может стать отличным руководством для автора, а он может не знать об этом конкретном разделе кодовой базы, если не работал с ним раньше.
9. Это не вы, это они
При чтении кода важно, чтобы вы могли легко его понимать. Если какая-то часть кода кажется непонятной, это не значит, что вы невнимательно прочитали код. Это означает, что код недостаточно ясен.
Если у вас есть проблемы с пониманием того, что делает этот фрагмент, другим разработчикам, вероятно, будет трудно понять его в будущем, когда им понадобится изменить эту часть кода. Когда вы обнаружите такой код, не стесняйтесь сообщить об этом. И не просто просите автора объяснить его, попросите переписать его. Если нельзя написать более понятно, хотя бы попросите автора добавить комментарии.
10. Ваше мнение не всегда правильно
Обычно существует более одного способа добиться цели. Читая фрагмент кода, вы, вероятно, представите другие способы сделать это и почувствуете желание предложить это в комментарии как лучшее решение. Иногда нужно спросить себя: действительно ли оно лучше или способ автора тоже хорош?
Если нет явного преимущества в сложности или удобочитаемости кода, подумайте дважды, прежде чем предлагать переписать его. Перечитайте код и убедитесь, что он соответствует принятым в вашей команде соглашениям, хорошо выполняет свою работу, и сравните его с альтернативным вариантом, чтобы увидеть, как это повлияет на качество кода. Если способ автора приемлем, но вы по-прежнему считаете, что ваш вариант лучше, напишите его как предложение, а не как обязательное изменение.
Источник: https://betterprogramming.pub/10-tips-to-write-effective-code-reviews-c25c25aa22c5
👍15
День 1140. #CodeReview
Про обзоры кода на канале было уже много постов. Найти их можно по тегу в заголовке. А сегодня, пока ютуб окончательно не заблокировали, порекомендую вам очередное видео от Дейва Пламера «The Secret Society of Code Reviewers at Microsoft»
В видео он рассказывает о том, зачем нужны обзоры кода, как они проходили в Майкрософт на заре систем контроля версий, 5 советов, как проводить обзоры кода, и 5 советов, чего не надо делать при обзорах кода.
PS: из-за скорости речи и некоторого акцента автора, понять его иногда довольно трудно. Можете поставить скорость 0,75 и включить субтитры.
Про обзоры кода на канале было уже много постов. Найти их можно по тегу в заголовке. А сегодня, пока ютуб окончательно не заблокировали, порекомендую вам очередное видео от Дейва Пламера «The Secret Society of Code Reviewers at Microsoft»
В видео он рассказывает о том, зачем нужны обзоры кода, как они проходили в Майкрософт на заре систем контроля версий, 5 советов, как проводить обзоры кода, и 5 советов, чего не надо делать при обзорах кода.
PS: из-за скорости речи и некоторого акцента автора, понять его иногда довольно трудно. Можете поставить скорость 0,75 и включить субтитры.
👍5
1154.png
1.8 MB
День 1154. #CodeReview
Пирамида Обзора Кода
В обзорах кода обычно много внимания и многословных дискуссий уделяется приземлённым аспектам, таким как форматирование и стиль кода, в то время как важные аспекты (делает ли изменение то, что должно делать, является ли оно производительным, является ли он обратно совместимым для существующих клиентов и многие другие), как правило, привлекают меньше внимания.
Чтобы повысить осведомленность об этой проблеме и предоставить некоторые рекомендации по аспектам, на которых следует сосредоточиться, представляю вам «Пирамиду Обзора Кода». Она призвана помочь сосредоточить внимание на тех частях обзора, которые наиболее важны, а также отметить, какие части могут и должны быть автоматизированы.
Основной принцип: Нижние части пирамиды должны лежать в основе код-ревью и занимать его большую часть.
Источник: https://www.morling.dev/blog/the-code-review-pyramid/
Пирамида Обзора Кода
В обзорах кода обычно много внимания и многословных дискуссий уделяется приземлённым аспектам, таким как форматирование и стиль кода, в то время как важные аспекты (делает ли изменение то, что должно делать, является ли оно производительным, является ли он обратно совместимым для существующих клиентов и многие другие), как правило, привлекают меньше внимания.
Чтобы повысить осведомленность об этой проблеме и предоставить некоторые рекомендации по аспектам, на которых следует сосредоточиться, представляю вам «Пирамиду Обзора Кода». Она призвана помочь сосредоточить внимание на тех частях обзора, которые наиболее важны, а также отметить, какие части могут и должны быть автоматизированы.
Основной принцип: Нижние части пирамиды должны лежать в основе код-ревью и занимать его большую часть.
Источник: https://www.morling.dev/blog/the-code-review-pyramid/
👍5
День 1297. #Юмор #CodeReview
Обзор Кода: Как Нажить Себе Врагов
Иногда люди на работе раздражают вас, и вы чувствуете, что нужно отыграться. Если вы разрабатываете ПО, то способ есть – обзор кода! Это фантастический способ отомстить с помощью пассивно-агрессивных действий.
Проверяющий
1. Комментарии о стиле кода
У большинства компаний есть рекомендации по стилю кода. Изучите их! А затем начните просить об изменениях, которые явно не упомянуты. Если в рекомендациях по стилю кода что-то не упоминается, то это отличный шанс попросить внести бессмысленные изменения, которые просто заставят вашу жертву поработать:
- Правильно ли названы методы в классе модульного теста?
- Не слишком ли многословно названа переменная?
- Не используется синтаксис Йоды? Попросите изменить условия на противоположные.
2. Попросите об изменениях, которые не имеют смысла
Шаг 1 раздражает, но сам по себе он не смертелен. Нужно продолжать давление. Далее идут бессмысленные запросы изменений.
Если есть два способа сделать что-то, потребуйте, чтобы код был изменён, чтобы сделать по-вашему. Не слушайте доказательств о недостатках вашего варианта. Включитесь в длинный спор почему это следует изменить.
Если не хватает аргументов заставьте соперника сомневаться в своих знаниях с помощью фраз вроде: «Я не знаю, почему вы так в штыки воспринимаете эту просьбу. Так, как я сказал, будет работать. Пожалуйста измените. Спасибо.»
Заставьте соперника потратить время на переписывание кода, который отлично работает.
3. Долгие задержки
Не торопитесь отвечать. Выждите как минимум 24 часа перед проверкой кода. Говорите, что заняты другими делами. Цель здесь состоит в том, чтобы сделать пулл-реквест (PR) устаревшим. Открытые PR считаются техническим долгом, потому что они требуют работы для поддержания. Это утомительная работа. Таким образом, вам нужно заставить PR провисеть как можно дольше, чтобы человеку приходилось тратить время на исправление конфликтов слияния.
Хороший способ сделать это — отказаться работать с PR, в котором есть конфликты слияния, потому что код может выглядеть по-другому после исправления, и вы не хотите тратить время на его просмотр, чтобы затем снова просматривать его после разрешения конфликтов. Это отличная тактика. Если сопернику не пришлось исправлять конфликты слияния хотя бы 2-3 раза, вы слишком быстро ему отвечаете!
4. Требуйте добавления багов
Просить о бесполезных изменениях — отличный способ добавить работы, но требовать внесения багов – это высший пилотаж! Ведь нужно поработать, чтобы добавить изменение, а затем соперник будет выглядеть глупо, когда ошибка обнаружится.
Проверяемый
1. Измените стиль кода в PR
Каждый PR, который вы отправляете на рассмотрение своему врагу, должен включать хотя бы 50% ненужных изменений стиля кода. Это сделает поиск фактических функциональных изменений настолько трудным, что он просто не глядя примет все ваши изменения.
2. Создавайте огромные PR
Ваша задача - заставить людей бояться обозревать ваш код. Это значит, что все PR должны содержать от 1000 изменений в как минимум 10 файлах.
Требуйте быстрого ответа. Это технический долг, и вы не хотите самостоятельно устранять конфликты слияния. Так что изводите всех, пока ваш PR не будет принят.
3. Игнорируйте комментарии
Отличный способ избежать негативных отзывов во время проверки кода — просто игнорировать их. Получили негативный комментарий? Попросите приятеля одобрить PR и слить его, не разбираясь с этим комментарием.
Итого
Если эти шаги повторять неоднократно и последовательно в течение нескольких месяцев, ваш враг пожалеет о том, что связался с вами!
Источник: http://repohealth.io/blog/code-review-how-to-make-enemies/
Обзор Кода: Как Нажить Себе Врагов
Иногда люди на работе раздражают вас, и вы чувствуете, что нужно отыграться. Если вы разрабатываете ПО, то способ есть – обзор кода! Это фантастический способ отомстить с помощью пассивно-агрессивных действий.
Проверяющий
1. Комментарии о стиле кода
У большинства компаний есть рекомендации по стилю кода. Изучите их! А затем начните просить об изменениях, которые явно не упомянуты. Если в рекомендациях по стилю кода что-то не упоминается, то это отличный шанс попросить внести бессмысленные изменения, которые просто заставят вашу жертву поработать:
- Правильно ли названы методы в классе модульного теста?
- Не слишком ли многословно названа переменная?
- Не используется синтаксис Йоды? Попросите изменить условия на противоположные.
2. Попросите об изменениях, которые не имеют смысла
Шаг 1 раздражает, но сам по себе он не смертелен. Нужно продолжать давление. Далее идут бессмысленные запросы изменений.
Если есть два способа сделать что-то, потребуйте, чтобы код был изменён, чтобы сделать по-вашему. Не слушайте доказательств о недостатках вашего варианта. Включитесь в длинный спор почему это следует изменить.
Если не хватает аргументов заставьте соперника сомневаться в своих знаниях с помощью фраз вроде: «Я не знаю, почему вы так в штыки воспринимаете эту просьбу. Так, как я сказал, будет работать. Пожалуйста измените. Спасибо.»
Заставьте соперника потратить время на переписывание кода, который отлично работает.
3. Долгие задержки
Не торопитесь отвечать. Выждите как минимум 24 часа перед проверкой кода. Говорите, что заняты другими делами. Цель здесь состоит в том, чтобы сделать пулл-реквест (PR) устаревшим. Открытые PR считаются техническим долгом, потому что они требуют работы для поддержания. Это утомительная работа. Таким образом, вам нужно заставить PR провисеть как можно дольше, чтобы человеку приходилось тратить время на исправление конфликтов слияния.
Хороший способ сделать это — отказаться работать с PR, в котором есть конфликты слияния, потому что код может выглядеть по-другому после исправления, и вы не хотите тратить время на его просмотр, чтобы затем снова просматривать его после разрешения конфликтов. Это отличная тактика. Если сопернику не пришлось исправлять конфликты слияния хотя бы 2-3 раза, вы слишком быстро ему отвечаете!
4. Требуйте добавления багов
Просить о бесполезных изменениях — отличный способ добавить работы, но требовать внесения багов – это высший пилотаж! Ведь нужно поработать, чтобы добавить изменение, а затем соперник будет выглядеть глупо, когда ошибка обнаружится.
Проверяемый
1. Измените стиль кода в PR
Каждый PR, который вы отправляете на рассмотрение своему врагу, должен включать хотя бы 50% ненужных изменений стиля кода. Это сделает поиск фактических функциональных изменений настолько трудным, что он просто не глядя примет все ваши изменения.
2. Создавайте огромные PR
Ваша задача - заставить людей бояться обозревать ваш код. Это значит, что все PR должны содержать от 1000 изменений в как минимум 10 файлах.
Требуйте быстрого ответа. Это технический долг, и вы не хотите самостоятельно устранять конфликты слияния. Так что изводите всех, пока ваш PR не будет принят.
3. Игнорируйте комментарии
Отличный способ избежать негативных отзывов во время проверки кода — просто игнорировать их. Получили негативный комментарий? Попросите приятеля одобрить PR и слить его, не разбираясь с этим комментарием.
Итого
Если эти шаги повторять неоднократно и последовательно в течение нескольких месяцев, ваш враг пожалеет о том, что связался с вами!
Источник: http://repohealth.io/blog/code-review-how-to-make-enemies/
👍12
День 1312. #CodeReview
Насколько Хорош Ваш Процесс Код-Ревью?
Если ваша команда считает код-ревью пустой тратой времени, то они правы. Те, кто не ценит проверки кода, откладывают их выполнение, часто мало чего находят, либо их комментарии носят чисто стилистический характер. В такой команде внедрение код-ревью может только ухудшить процесс разработки, замедлив его без улучшения качества кода.
Можно построить процесс проверки кода, который будет повышать эффективность, но нужно действовать целенаправленно. Во-первых, организация должна договориться о целях. Во-вторых, нужно регулярно отслеживать показатели проверки, чтобы убедиться, что цели достигнуты и процесс работает исправно.
Согласованность
Эффективный процесс код-ревью начинается с согласования цели - под какие результаты оптимизируется процесс? Выявление ошибок, улучшение сопровождаемости, повышение стилистической согласованности или обмен знаниями в команде? Определение приоритетов поможет команде сосредоточиться на том, какие отзывы оставлять и что искать.
Ключевые показатели
Метрики могут быть разными в зависимости от целей, но есть несколько общих, которые позволят быстро диагностировать и устранять проблемы, связанные с процессом проверки.
1. Скорость
«Время до первого отзыва» — среднее время ожидания отзыва отправителем. Когда этот показатель высок, отправители либо тратят время на ожидание, либо вынуждены делать что-то другое. Если это происходит, важно согласовать ожидания от проверки кода и то, как проверки могут быть лучше интегрированы в повседневные процессы. Определите, что для вас означает «низкое» время до первого отзыва. Относительно этого можно углубляться в индивидуальные и командные показатели: размер пул-реквестов, баланс рабочей нагрузки и скорость проверки. Важно снизить время до первого отзыва настолько, насколько это возможно, без ущерба для внимания и производительности рецензентов.
2. Покрытие
Если ваша цель — улучшить качество кода и выявить ошибки, важно сравнить количество файлов с комментариями в обзоре с количеством изменённых файлов в пул-реквесте. Это будет показателем тщательности проверки. Не существует оптимального числа, но вы должны убедиться, что результат соответствует ожиданиям. Чтобы рецензенты не просто проштамповывали любые изменения, но, и чтобы не сильно придирались и не замедляли процесс.
3. Влияние
Одно только покрытие отзывами не говорит о качестве кода. Важно посмотреть, все ли эти отзывы приводят к действиям? Для этого отслеживайте процент комментариев, которые приводят к ответным комментариям или изменениям в коде. Большое количество комментариев с низким «влиянием» указывает на то, что отзывы рецензентов не воспринимаются как ценные для отправителя. Это может потребовать перестройки того, как должны проводиться проверки кода.
4. Циклы
Пулл-реквесты, перескакивающие туда-сюда между автором и рецензентом, могут замедлять процесс. Если это происходит часто, процесс рецензирования может стать узким местом и источником демотивации для инженеров, пытающихся завершить свою работу.
Средний показатель может меняться по многим причинам. Привлечение новых разработчиков может вызвать всплеск. Однако такой всплеск в опытной команде часто является признаком рассогласованности представлений:
- о том, что значит «готово»,
- какие изменения ожидаются после комментария,
- как должно быть реализовано решение.
Если количество циклов проверки для определённого отправителя велико, это может означать, что он не понимает кодовую базу или имеет дело с нечёткими требованиями.
Проверка кода — один из самых сложных процессов в команде разработчиков ПО. В каждой команде существует свой идеальный баланс тщательности и скорости, и этот баланс может даже измениться для данной команды из-за изменения приоритетов. Менеджеры должны постоянно следить за процессом код-ревью, беседовать с командой, чтобы собрать информацию, необходимую для придания контекста метрикам проверки кода и придания им значимости.
Источник: https://thenewstack.io/how-good-is-your-code-review-process/
Насколько Хорош Ваш Процесс Код-Ревью?
Если ваша команда считает код-ревью пустой тратой времени, то они правы. Те, кто не ценит проверки кода, откладывают их выполнение, часто мало чего находят, либо их комментарии носят чисто стилистический характер. В такой команде внедрение код-ревью может только ухудшить процесс разработки, замедлив его без улучшения качества кода.
Можно построить процесс проверки кода, который будет повышать эффективность, но нужно действовать целенаправленно. Во-первых, организация должна договориться о целях. Во-вторых, нужно регулярно отслеживать показатели проверки, чтобы убедиться, что цели достигнуты и процесс работает исправно.
Согласованность
Эффективный процесс код-ревью начинается с согласования цели - под какие результаты оптимизируется процесс? Выявление ошибок, улучшение сопровождаемости, повышение стилистической согласованности или обмен знаниями в команде? Определение приоритетов поможет команде сосредоточиться на том, какие отзывы оставлять и что искать.
Ключевые показатели
Метрики могут быть разными в зависимости от целей, но есть несколько общих, которые позволят быстро диагностировать и устранять проблемы, связанные с процессом проверки.
1. Скорость
«Время до первого отзыва» — среднее время ожидания отзыва отправителем. Когда этот показатель высок, отправители либо тратят время на ожидание, либо вынуждены делать что-то другое. Если это происходит, важно согласовать ожидания от проверки кода и то, как проверки могут быть лучше интегрированы в повседневные процессы. Определите, что для вас означает «низкое» время до первого отзыва. Относительно этого можно углубляться в индивидуальные и командные показатели: размер пул-реквестов, баланс рабочей нагрузки и скорость проверки. Важно снизить время до первого отзыва настолько, насколько это возможно, без ущерба для внимания и производительности рецензентов.
2. Покрытие
Если ваша цель — улучшить качество кода и выявить ошибки, важно сравнить количество файлов с комментариями в обзоре с количеством изменённых файлов в пул-реквесте. Это будет показателем тщательности проверки. Не существует оптимального числа, но вы должны убедиться, что результат соответствует ожиданиям. Чтобы рецензенты не просто проштамповывали любые изменения, но, и чтобы не сильно придирались и не замедляли процесс.
3. Влияние
Одно только покрытие отзывами не говорит о качестве кода. Важно посмотреть, все ли эти отзывы приводят к действиям? Для этого отслеживайте процент комментариев, которые приводят к ответным комментариям или изменениям в коде. Большое количество комментариев с низким «влиянием» указывает на то, что отзывы рецензентов не воспринимаются как ценные для отправителя. Это может потребовать перестройки того, как должны проводиться проверки кода.
4. Циклы
Пулл-реквесты, перескакивающие туда-сюда между автором и рецензентом, могут замедлять процесс. Если это происходит часто, процесс рецензирования может стать узким местом и источником демотивации для инженеров, пытающихся завершить свою работу.
Средний показатель может меняться по многим причинам. Привлечение новых разработчиков может вызвать всплеск. Однако такой всплеск в опытной команде часто является признаком рассогласованности представлений:
- о том, что значит «готово»,
- какие изменения ожидаются после комментария,
- как должно быть реализовано решение.
Если количество циклов проверки для определённого отправителя велико, это может означать, что он не понимает кодовую базу или имеет дело с нечёткими требованиями.
Проверка кода — один из самых сложных процессов в команде разработчиков ПО. В каждой команде существует свой идеальный баланс тщательности и скорости, и этот баланс может даже измениться для данной команды из-за изменения приоритетов. Менеджеры должны постоянно следить за процессом код-ревью, беседовать с командой, чтобы собрать информацию, необходимую для придания контекста метрикам проверки кода и придания им значимости.
Источник: https://thenewstack.io/how-good-is-your-code-review-process/
👍7
День 1326. #CodeReview
Советы по Улучшению Обзоров Кода на GitHub
У большинства компаний и команд есть специальные стандарты, определяющие, как должен выглядеть обзор и сколько согласований вам нужно, прежде чем слить код в основную ветку. У GitHub есть специальные инструменты для поддержки обзоров кода в своих средах.
1. Защищённые ветки
Защитите основную ветку от случайных изменений. Push чего-либо непосредственно в основную ветку не должен быть возможным. К счастью, GitHub предлагает отличный механизм для защиты веток. Вы можете создать специальные правила, определив, например, что для слияния кода с основной веткой требуется пул-реквест и одобрение хотя бы одного рецензента.
Как это настроить?
- В репозитории на GitHub перейдите на вкладку Settings (Настройки).
- В меню слева нажмите Branches (Ветки).
- В разделе Branch protection rules (Правила защиты веток) нажмите Add rule (Добавить правило).
- Введите имя ветки или регулярное выражение для шаблона имени.
- Выберите один из пунктов, из списка правил и сохраните изменения.
2. Метки
Метки — это дополнительные, легко распознаваемые фрагменты информации, видимые в списках пул-реквестов. Вы можете использовать их, например, чтобы различать внутренние и внешние изменения, запросы на слияние, связанные с конкретными функциями вашего приложения, типом изменений или размером. Использование меток значительно упрощает управление слияниями.
Как создать новую метку?
- В репозитории на GitHub перейдите в раздел Pull Requests.
- Щёлкните на кнопку Labels (Метки) рядом с полем фильтра.
- Нажмите зелёную кнопку New label (Новая метка).
- Заполните все поля в форме и нажмите кнопку Create label (Создать метку).
- Теперь вы можете назначить её любому из ваших новых или существующих мерж-реквестов в форме создания пул-реквеста.
3. Автоматические проверки
Многие вещи, такие как синтаксис или выполнение тестов, могут выполняться автоматически. Вы можете использовать Jenkins/Github Actions/CircleCI или любой другой инструмент по вашему выбору, чтобы запускать автоматические тесты при каждом создании пул-реквеста. Добавьте правило для отказа в слиянии до тех пор, пока не будут пройдены все необходимые проверки. В один прекрасный день это может спасти ваш производственный код! Добавьте также способ лёгкого повторного запуска этих тестов вручную . Например, отправка специального сообщения в комментарии на GitHub. Это очень полезно при отладке.
4. Шаблон сообщения пул-реквеста с контрольным списком
Каждый запрос на слияние должен иметь хороший, короткий и говорящий сам за себя заголовок и некоторое описание, возможно ссылку на задачу в баг-трекере. Кроме того, некоторые вещи нельзя протестировать вручную, например, доступность или выполнение бизнес-требований. Со временем становится всё труднее помнить все те вещи, которые нужно указать в сообщении мерж-реквеста вам, как автору, и вещи, которые нужно проверить вам, как рецензенту. Вы можете легко решить эти проблемы, используя шаблоны для мерж-реквестов. Это черновик сообщения с контрольным списком вещей, которые нужно проверить вручную, когда вы создаёте запрос на слияние, и этого достаточно, чтобы заполнить форму необходимой информацией и отметить все пункты в контрольном списке как выполненные.
Как добавить шаблон?
- Откройте свой репозиторий в своем любимом редакторе кода.
- Добавьте файл pull_request_template.md в корень вашего репозитория или папку docs, расположенную в корне.
- Поместите свой шаблон внутрь файла (вы можете использовать синтаксис markdown для создания заголовков, контрольных списков и т. д.).
- Слейте изменения с основной веткой.
- Если вы хотите иметь более 1 шаблона сообщения, создайте каталог PULL_REQUEST_TEMPLATE (также в корне или в папке docs) и храните там файлы markdown. В этом случае пользователь сможет выбрать один из шаблонов, используя раскрывающееся меню во время создания запроса на слияние.
Источник: https://dev.to/this-is-learning/5-tips-to-improve-your-code-reviews-on-github-gja
Советы по Улучшению Обзоров Кода на GitHub
У большинства компаний и команд есть специальные стандарты, определяющие, как должен выглядеть обзор и сколько согласований вам нужно, прежде чем слить код в основную ветку. У GitHub есть специальные инструменты для поддержки обзоров кода в своих средах.
1. Защищённые ветки
Защитите основную ветку от случайных изменений. Push чего-либо непосредственно в основную ветку не должен быть возможным. К счастью, GitHub предлагает отличный механизм для защиты веток. Вы можете создать специальные правила, определив, например, что для слияния кода с основной веткой требуется пул-реквест и одобрение хотя бы одного рецензента.
Как это настроить?
- В репозитории на GitHub перейдите на вкладку Settings (Настройки).
- В меню слева нажмите Branches (Ветки).
- В разделе Branch protection rules (Правила защиты веток) нажмите Add rule (Добавить правило).
- Введите имя ветки или регулярное выражение для шаблона имени.
- Выберите один из пунктов, из списка правил и сохраните изменения.
2. Метки
Метки — это дополнительные, легко распознаваемые фрагменты информации, видимые в списках пул-реквестов. Вы можете использовать их, например, чтобы различать внутренние и внешние изменения, запросы на слияние, связанные с конкретными функциями вашего приложения, типом изменений или размером. Использование меток значительно упрощает управление слияниями.
Как создать новую метку?
- В репозитории на GitHub перейдите в раздел Pull Requests.
- Щёлкните на кнопку Labels (Метки) рядом с полем фильтра.
- Нажмите зелёную кнопку New label (Новая метка).
- Заполните все поля в форме и нажмите кнопку Create label (Создать метку).
- Теперь вы можете назначить её любому из ваших новых или существующих мерж-реквестов в форме создания пул-реквеста.
3. Автоматические проверки
Многие вещи, такие как синтаксис или выполнение тестов, могут выполняться автоматически. Вы можете использовать Jenkins/Github Actions/CircleCI или любой другой инструмент по вашему выбору, чтобы запускать автоматические тесты при каждом создании пул-реквеста. Добавьте правило для отказа в слиянии до тех пор, пока не будут пройдены все необходимые проверки. В один прекрасный день это может спасти ваш производственный код! Добавьте также способ лёгкого повторного запуска этих тестов вручную . Например, отправка специального сообщения в комментарии на GitHub. Это очень полезно при отладке.
4. Шаблон сообщения пул-реквеста с контрольным списком
Каждый запрос на слияние должен иметь хороший, короткий и говорящий сам за себя заголовок и некоторое описание, возможно ссылку на задачу в баг-трекере. Кроме того, некоторые вещи нельзя протестировать вручную, например, доступность или выполнение бизнес-требований. Со временем становится всё труднее помнить все те вещи, которые нужно указать в сообщении мерж-реквеста вам, как автору, и вещи, которые нужно проверить вам, как рецензенту. Вы можете легко решить эти проблемы, используя шаблоны для мерж-реквестов. Это черновик сообщения с контрольным списком вещей, которые нужно проверить вручную, когда вы создаёте запрос на слияние, и этого достаточно, чтобы заполнить форму необходимой информацией и отметить все пункты в контрольном списке как выполненные.
Как добавить шаблон?
- Откройте свой репозиторий в своем любимом редакторе кода.
- Добавьте файл pull_request_template.md в корень вашего репозитория или папку docs, расположенную в корне.
- Поместите свой шаблон внутрь файла (вы можете использовать синтаксис markdown для создания заголовков, контрольных списков и т. д.).
- Слейте изменения с основной веткой.
- Если вы хотите иметь более 1 шаблона сообщения, создайте каталог PULL_REQUEST_TEMPLATE (также в корне или в папке docs) и храните там файлы markdown. В этом случае пользователь сможет выбрать один из шаблонов, используя раскрывающееся меню во время создания запроса на слияние.
Источник: https://dev.to/this-is-learning/5-tips-to-improve-your-code-reviews-on-github-gja
👍6
День 1329. #CodeReview
Допрашиваем Незнакомый Код. Начало
Читаемый код — это хорошо, но не весь код будет читаемым. Популярное утверждение о коде, что его читают в десять раз чаще, чем пишут. Точных цифр нет, но скорее реальное соотношение ближе к 100:1. И чем больше срок службы продукта, тем оно выше. Книги и пособия обычно фокусируются на написании кода, но чтение кода — это отдельный навык.
Новичкам часто кажется, что, если не тратить большую часть времени на добавление нового кода в проект, они не работают продуктивно. На самом деле, первые 80-95% времени должны быть потрачены на чтение кода и других форм документации. Иногда это даже 100%: в процессе изучения кода вы можете узнать, что эта функция уже существует, просто о ней забыли или это принесёт больше вреда, чем пользы.
Рассмотрим наиболее практичные тактики чтения кода и полезные инструменты, которые нужно иметь и сочетать их в зависимости от ситуации.
1. Изучите IDE и установите полезные плагины
Ваша IDE — бесценный инструмент для понимания кода. Однако стоит потратить время, чтобы найти полезные плагины, которые облегчат чтение и понимание кода. Ищите следующие функции:
- Подсветку синтаксиса: ключевые слова, имена классов/методов/полей/переменных,… скобки.
- Автоформатирование
- Статический анализ
- Контекстная навигация: позволит быстро перейти к определению, просмотреть реализации и просмотреть использования класса или метода.
- Рефакторинг: автоматизирует частые рефакторинги, такие как извлечение логики в метод, изменение параметров метода или переименование переменной.
- Подсказки по коду: тип, параметры, документация о классе/методе/поле, при наведении курсора.
- Средство запуска тестов.
- Отладчик.
- Интеграция с системой контроля версий: помимо очевидного, предоставляет информацию об авторе и дате последнего редактирования каждой строки кода.
Вы можете (а иногда, возможно, придётся) читать код без этих инструментов. Но они упрощают проверку ваших предположений и сбор контекста, и вы с большей вероятностью будете принимать правильные решения и меньше гадать.
2. Прочитайте код как минимум дважды
Одного прочтения почти никогда не бывает достаточно, чтобы полностью понять, что делает фрагмент кода. Дважды - это самый минимум.
При первом чтении постарайтесь получить общую картину, просматривая и создавая схему в уме (или на бумаге). Ваша цель — общее представление о том, что делает код. Если под рукой есть резиновая уточка, - самое время поговорить с ней. Объясните общую цель кода. Если какие-то части будет сложно объяснить, это привлечёт к ним внимание.
Второе чтение больше касается деталей. Убедитесь, что вы понимаете каждую строку или хотя бы имеете теорию об этом. Обратите особое внимание на внешние эффекты. Какие методы вызываются? Обновляется ли общее состояние? Какие значения возвращаются? Потратьте время на изучение каждого метода, чтобы понять всю логику, даже если она находится за пределами изучаемого кода. Перейдите к другим методам, посмотрите документацию библиотечных методов, проверьте, что значит каждый фрагмент, вызывающий сомнения. Когда вы закончите, у вас будут теории о возможном поведении, пограничных случаях и условиях отказа в коде. Могут быть части, которые вы не понимаете, но они почти всегда следуют простым правилам, которые можно нагуглить или узнать у товарища по команде.
Третье прочтение полезно, если код содержит сложную логику. Выберите простые значения для любых параметров или переменных и представьте, что они проходят через код сверху вниз. Просчитайте результаты каждой строки.
На самом деле, каждое чтение может включать в себя несколько проходов и несколько походов в Google и на Stack Overflow. Совершенно нормально читать кусок кода десять или более раз, прежде чем вы действительно его поймёте. Может помочь длительный перерыв после первых нескольких прочтений, особенно если вы имеете дело с новыми для вас понятиями.
Продолжение следует…
Источник: https://stackoverflow.blog/2022/08/15/how-to-interrogate-unfamiliar-code/
Допрашиваем Незнакомый Код. Начало
Читаемый код — это хорошо, но не весь код будет читаемым. Популярное утверждение о коде, что его читают в десять раз чаще, чем пишут. Точных цифр нет, но скорее реальное соотношение ближе к 100:1. И чем больше срок службы продукта, тем оно выше. Книги и пособия обычно фокусируются на написании кода, но чтение кода — это отдельный навык.
Новичкам часто кажется, что, если не тратить большую часть времени на добавление нового кода в проект, они не работают продуктивно. На самом деле, первые 80-95% времени должны быть потрачены на чтение кода и других форм документации. Иногда это даже 100%: в процессе изучения кода вы можете узнать, что эта функция уже существует, просто о ней забыли или это принесёт больше вреда, чем пользы.
Рассмотрим наиболее практичные тактики чтения кода и полезные инструменты, которые нужно иметь и сочетать их в зависимости от ситуации.
1. Изучите IDE и установите полезные плагины
Ваша IDE — бесценный инструмент для понимания кода. Однако стоит потратить время, чтобы найти полезные плагины, которые облегчат чтение и понимание кода. Ищите следующие функции:
- Подсветку синтаксиса: ключевые слова, имена классов/методов/полей/переменных,… скобки.
- Автоформатирование
- Статический анализ
- Контекстная навигация: позволит быстро перейти к определению, просмотреть реализации и просмотреть использования класса или метода.
- Рефакторинг: автоматизирует частые рефакторинги, такие как извлечение логики в метод, изменение параметров метода или переименование переменной.
- Подсказки по коду: тип, параметры, документация о классе/методе/поле, при наведении курсора.
- Средство запуска тестов.
- Отладчик.
- Интеграция с системой контроля версий: помимо очевидного, предоставляет информацию об авторе и дате последнего редактирования каждой строки кода.
Вы можете (а иногда, возможно, придётся) читать код без этих инструментов. Но они упрощают проверку ваших предположений и сбор контекста, и вы с большей вероятностью будете принимать правильные решения и меньше гадать.
2. Прочитайте код как минимум дважды
Одного прочтения почти никогда не бывает достаточно, чтобы полностью понять, что делает фрагмент кода. Дважды - это самый минимум.
При первом чтении постарайтесь получить общую картину, просматривая и создавая схему в уме (или на бумаге). Ваша цель — общее представление о том, что делает код. Если под рукой есть резиновая уточка, - самое время поговорить с ней. Объясните общую цель кода. Если какие-то части будет сложно объяснить, это привлечёт к ним внимание.
Второе чтение больше касается деталей. Убедитесь, что вы понимаете каждую строку или хотя бы имеете теорию об этом. Обратите особое внимание на внешние эффекты. Какие методы вызываются? Обновляется ли общее состояние? Какие значения возвращаются? Потратьте время на изучение каждого метода, чтобы понять всю логику, даже если она находится за пределами изучаемого кода. Перейдите к другим методам, посмотрите документацию библиотечных методов, проверьте, что значит каждый фрагмент, вызывающий сомнения. Когда вы закончите, у вас будут теории о возможном поведении, пограничных случаях и условиях отказа в коде. Могут быть части, которые вы не понимаете, но они почти всегда следуют простым правилам, которые можно нагуглить или узнать у товарища по команде.
Третье прочтение полезно, если код содержит сложную логику. Выберите простые значения для любых параметров или переменных и представьте, что они проходят через код сверху вниз. Просчитайте результаты каждой строки.
На самом деле, каждое чтение может включать в себя несколько проходов и несколько походов в Google и на Stack Overflow. Совершенно нормально читать кусок кода десять или более раз, прежде чем вы действительно его поймёте. Может помочь длительный перерыв после первых нескольких прочтений, особенно если вы имеете дело с новыми для вас понятиями.
Продолжение следует…
Источник: https://stackoverflow.blog/2022/08/15/how-to-interrogate-unfamiliar-code/
👍9
День 1330. #CodeReview
Допрашиваем Незнакомый Код. Продолжение
Начало
3. Рефакторинг имён локальных переменных и методов
Иногда часть кода настолько расплывчата или вводит в заблуждение, что её трудно осмыслить. Один практически безрисковый способ — переименовать локальные переменные и приватные методы, чтобы более точно описать, что они делают. Эти изменения не повлияют ни на что за пределами файла, с которым вы работаете, и не вызовут ошибок, если вы будете осторожны, чтобы избежать конфликтов имен. Если возможно, используйте инструменты рефакторинга IDE, а не поиск и замену текста.
Возможно, стоит внести и другие улучшения (например, предложенные статическим анализатором кода), но даже переименование нескольких плохо названных идентификаторов поможет понять код, не меняя его логики и не задумываясь обо всех его частях одновременно. Сами решайте, фиксировать ли эти изменения. Улучшение читабельности кода будет приносить пользу всей команде снова и снова, даже если оно не добавляет и не изменяет функциональность.
4. Посмотрите, как используется код
Большая часть кода используется другим кодом. Понимание ситуации, в которой код используется, может быть ценным контекстом для выяснения того, что он делает.
В идеале IDE покажет все места, где используется метод. Если такой функции нет, можно попробовать переименовать метод во что-нибудь нелепое. Ошибки компиляции сообщат, где использовался метод. Не забудьте изменить имя обратно. Если ваш язык интерпретируемый, придётся использовать текстовый поиск по имени метода и копаться в результатах.
5. Поищите похожий код
Иногда код трудно понять, даже если все идентификаторы правильно названы и варианты использования знакомы. Иногда для конкретной операции нет идиомы. В худшем случае рассматриваемый код либо уникален для кодовой базы, либо нет очевидной фразы, которую вы могли бы погуглить, чтобы узнать больше.
Хорошая новость в том, что по-настоящему уникальный код встречается редко в долгоживущих кодовых базах, особенно на уровне одного выражения или строки кода. Если вы потратите несколько минут на поиск похожего кода в проекте, вы можете найти что-то, что поможет разгадать загадку.
Полнотекстовый поиск — самая простая версия. Если вы хотите сузить результаты, поищите с помощью регулярного выражения. Также стоит потратить время на изучение некоторых продвинутых методов. Многие программисты предпочитают инструменты командной строки Unix, такие как grep и awk, или, в Windows, рукописные сценарии PowerShell.
Цель в том, чтобы сузить поиск до нескольких файлов, которые, скорее всего, будут отражать изучаемый вами процесс. Это позволит взглянуть на код с другой стороны и, возможно, лучше его понять.
6. Запустите модульные тесты
В идеальном мире тесты — всё, что вам нужно, чтобы понять поведение любого участка кода. Большинство кодовых баз не соответствуют этому идеалу. Тем не менее, рекомендуется проверить наличие тестов, выполняющих код, который вы изучаете. По крайней мере, они будут описывать входные и выходные данные.
Если тестов нет или они недостаточно полны, это вторая возможность внести некоторые положительные изменения. Напишите тест или два, чтобы ответить на вопросы, которые у вас остались о коде. Вы можете зафиксировать их, повысив стабильность кодовой базы и сделав её более самодокументируемой для всех, кто с ней сталкивается. И не нужно беспокоиться о том, что добавление теста как-то нарушит существующую функциональность.
Для написания тестов требуется время, но они гораздо более эффективны, чем прогон кода в воображении. Они являются фактическим доказательством того, что код работает определённым образом. И если вам в итоге потребуется изменить код, тесты дадут вам уверенность, что вы его не сломаете.
Окончание следует …
Источник: https://stackoverflow.blog/2022/08/15/how-to-interrogate-unfamiliar-code/
Допрашиваем Незнакомый Код. Продолжение
Начало
3. Рефакторинг имён локальных переменных и методов
Иногда часть кода настолько расплывчата или вводит в заблуждение, что её трудно осмыслить. Один практически безрисковый способ — переименовать локальные переменные и приватные методы, чтобы более точно описать, что они делают. Эти изменения не повлияют ни на что за пределами файла, с которым вы работаете, и не вызовут ошибок, если вы будете осторожны, чтобы избежать конфликтов имен. Если возможно, используйте инструменты рефакторинга IDE, а не поиск и замену текста.
Возможно, стоит внести и другие улучшения (например, предложенные статическим анализатором кода), но даже переименование нескольких плохо названных идентификаторов поможет понять код, не меняя его логики и не задумываясь обо всех его частях одновременно. Сами решайте, фиксировать ли эти изменения. Улучшение читабельности кода будет приносить пользу всей команде снова и снова, даже если оно не добавляет и не изменяет функциональность.
4. Посмотрите, как используется код
Большая часть кода используется другим кодом. Понимание ситуации, в которой код используется, может быть ценным контекстом для выяснения того, что он делает.
В идеале IDE покажет все места, где используется метод. Если такой функции нет, можно попробовать переименовать метод во что-нибудь нелепое. Ошибки компиляции сообщат, где использовался метод. Не забудьте изменить имя обратно. Если ваш язык интерпретируемый, придётся использовать текстовый поиск по имени метода и копаться в результатах.
5. Поищите похожий код
Иногда код трудно понять, даже если все идентификаторы правильно названы и варианты использования знакомы. Иногда для конкретной операции нет идиомы. В худшем случае рассматриваемый код либо уникален для кодовой базы, либо нет очевидной фразы, которую вы могли бы погуглить, чтобы узнать больше.
Хорошая новость в том, что по-настоящему уникальный код встречается редко в долгоживущих кодовых базах, особенно на уровне одного выражения или строки кода. Если вы потратите несколько минут на поиск похожего кода в проекте, вы можете найти что-то, что поможет разгадать загадку.
Полнотекстовый поиск — самая простая версия. Если вы хотите сузить результаты, поищите с помощью регулярного выражения. Также стоит потратить время на изучение некоторых продвинутых методов. Многие программисты предпочитают инструменты командной строки Unix, такие как grep и awk, или, в Windows, рукописные сценарии PowerShell.
Цель в том, чтобы сузить поиск до нескольких файлов, которые, скорее всего, будут отражать изучаемый вами процесс. Это позволит взглянуть на код с другой стороны и, возможно, лучше его понять.
6. Запустите модульные тесты
В идеальном мире тесты — всё, что вам нужно, чтобы понять поведение любого участка кода. Большинство кодовых баз не соответствуют этому идеалу. Тем не менее, рекомендуется проверить наличие тестов, выполняющих код, который вы изучаете. По крайней мере, они будут описывать входные и выходные данные.
Если тестов нет или они недостаточно полны, это вторая возможность внести некоторые положительные изменения. Напишите тест или два, чтобы ответить на вопросы, которые у вас остались о коде. Вы можете зафиксировать их, повысив стабильность кодовой базы и сделав её более самодокументируемой для всех, кто с ней сталкивается. И не нужно беспокоиться о том, что добавление теста как-то нарушит существующую функциональность.
Для написания тестов требуется время, но они гораздо более эффективны, чем прогон кода в воображении. Они являются фактическим доказательством того, что код работает определённым образом. И если вам в итоге потребуется изменить код, тесты дадут вам уверенность, что вы его не сломаете.
Окончание следует …
Источник: https://stackoverflow.blog/2022/08/15/how-to-interrogate-unfamiliar-code/
👍3
День 1331. #CodeReview
Допрашиваем Незнакомый Код. Окончание
Начало
Продолжение
7. Используйте отладчик
Выполните код по шагам в отладчике. Если вы знаете, какие действия пользователя запускают код, установите точку останова в начале кода, запустите программу в обычном режиме, взаимодействуя с ее интерфейсом, чтобы запустить код. Это дольше, чем запустить отладку в тесте, но так вы используете более реалистичные данные, которые могут помочь вам заметить такие вещи, как нулевые ссылки и пограничные случаи.
Отладка может быть менее полезной для кода, который выполняется десятки или сотни раз, например, для вложенных циклов. В этом случае вы можете добавить переменные, которые собирают данные на каждой итерации, чтобы просмотреть их позже. Многие IDE также позволяют устанавливать условные точки останова, чтобы можно было приостановить выполнение итерации, отвечающей определенным требованиям.
8. Поиск в базе знаний
Если ваша команда использует базу знаний, такую как Stack Overflow for Teams, Confluence или GitHub-вики, вы уже должны иметь довольно хорошее представление о том, какие термины или понятия можно использовать для поиска соответствующей документации. Имейте в виду, что документация не должна быть вашим единственным источником правды. Она начинает устаревать в момент публикации, и единственное, на что вы можете полностью положиться, чтобы узнать, как ведёт себя часть кода, — это сам код. Тем не менее, даже устаревшая документация может дать достаточно исходной информации и контекста, чтобы помочь вам избежать ошибочных выводов.
Документация может объяснить скорее не «как», а «почему» код работает так, а не иначе. Иногда вы понимаете, что делает фрагмент кода, но что-то в нем кажется неправильным. Прежде чем изменить его, вы должны приложить все усилия, чтобы понять, чем руководствовался первоначальный программист.
9. Используйте аннотацию контроля версий (git blame)
Последний способ собрать контекст — отследить исходного автора, коммит и тикет, связанный с этим кодом.
В любой системе контроля версий есть инструмент, который раскрывает автора и коммит для любой строки кода в кодовой базе. В Git это команда git blame. Так вы сможете найти исходный запрос, который включал код, и возможно, ссылку на исходный тикет, в котором содержится описание функции или ошибки. Возможно, придется просмотреть историю изменений файла, чтобы найти коммит, в котором было сделано нужное изменение.
Так вы сможете найти автора, рецензентов пул-реквеста, всех, кто комментировал тикет или ещё каким-либо образом имел отношение к изменению. Если вы до сих пор не поговорили с коллегами о возникшем у вас затруднении, теперь самое время.
Итого
Контекст и понимание, которые вы получили в ходе этих шагов, вероятно, будут ценны в будущем. Прежде чем двигаться дальше, рассмотрите возможность рефакторинга кода для ясности, создайте новую документацию или даже просто отправьте email с вашими выводами. Каждый раз, когда вы инвестируете в это, вы будете получать дивиденды, поскольку вы и ваша команда будете взаимодействовать с кодом в будущем.
Способность эффективно читать код — это секретное оружие, которое ускорит прохождение вами технического собеседования и сделает вас незаменимым членом любой команды. Программисты, умеющие писать код, ценны, но программисты, умеющие читать код, возможно, ещё более ценны. Когда в продакшене есть ошибка или нужно срочно создать фичу, первым и самым важным шагом является понимание. Умение читать код поможет вам в этом.
Источник: https://stackoverflow.blog/2022/08/15/how-to-interrogate-unfamiliar-code/
Допрашиваем Незнакомый Код. Окончание
Начало
Продолжение
7. Используйте отладчик
Выполните код по шагам в отладчике. Если вы знаете, какие действия пользователя запускают код, установите точку останова в начале кода, запустите программу в обычном режиме, взаимодействуя с ее интерфейсом, чтобы запустить код. Это дольше, чем запустить отладку в тесте, но так вы используете более реалистичные данные, которые могут помочь вам заметить такие вещи, как нулевые ссылки и пограничные случаи.
Отладка может быть менее полезной для кода, который выполняется десятки или сотни раз, например, для вложенных циклов. В этом случае вы можете добавить переменные, которые собирают данные на каждой итерации, чтобы просмотреть их позже. Многие IDE также позволяют устанавливать условные точки останова, чтобы можно было приостановить выполнение итерации, отвечающей определенным требованиям.
8. Поиск в базе знаний
Если ваша команда использует базу знаний, такую как Stack Overflow for Teams, Confluence или GitHub-вики, вы уже должны иметь довольно хорошее представление о том, какие термины или понятия можно использовать для поиска соответствующей документации. Имейте в виду, что документация не должна быть вашим единственным источником правды. Она начинает устаревать в момент публикации, и единственное, на что вы можете полностью положиться, чтобы узнать, как ведёт себя часть кода, — это сам код. Тем не менее, даже устаревшая документация может дать достаточно исходной информации и контекста, чтобы помочь вам избежать ошибочных выводов.
Документация может объяснить скорее не «как», а «почему» код работает так, а не иначе. Иногда вы понимаете, что делает фрагмент кода, но что-то в нем кажется неправильным. Прежде чем изменить его, вы должны приложить все усилия, чтобы понять, чем руководствовался первоначальный программист.
9. Используйте аннотацию контроля версий (git blame)
Последний способ собрать контекст — отследить исходного автора, коммит и тикет, связанный с этим кодом.
В любой системе контроля версий есть инструмент, который раскрывает автора и коммит для любой строки кода в кодовой базе. В Git это команда git blame. Так вы сможете найти исходный запрос, который включал код, и возможно, ссылку на исходный тикет, в котором содержится описание функции или ошибки. Возможно, придется просмотреть историю изменений файла, чтобы найти коммит, в котором было сделано нужное изменение.
Так вы сможете найти автора, рецензентов пул-реквеста, всех, кто комментировал тикет или ещё каким-либо образом имел отношение к изменению. Если вы до сих пор не поговорили с коллегами о возникшем у вас затруднении, теперь самое время.
Итого
Контекст и понимание, которые вы получили в ходе этих шагов, вероятно, будут ценны в будущем. Прежде чем двигаться дальше, рассмотрите возможность рефакторинга кода для ясности, создайте новую документацию или даже просто отправьте email с вашими выводами. Каждый раз, когда вы инвестируете в это, вы будете получать дивиденды, поскольку вы и ваша команда будете взаимодействовать с кодом в будущем.
Способность эффективно читать код — это секретное оружие, которое ускорит прохождение вами технического собеседования и сделает вас незаменимым членом любой команды. Программисты, умеющие писать код, ценны, но программисты, умеющие читать код, возможно, ещё более ценны. Когда в продакшене есть ошибка или нужно срочно создать фичу, первым и самым важным шагом является понимание. Умение читать код поможет вам в этом.
Источник: https://stackoverflow.blog/2022/08/15/how-to-interrogate-unfamiliar-code/
👍10
День 1465. #CodeReview
Как Оптимизировать Обзоры Кода
Обзоры кода требуют значительных временных затрат, и важно понять, как инженеры могут извлечь из них максимальную пользу. Процесс проверки кода (с помощью некоторой автоматизации) может быть идеальной возможностью для членов команд развить навыки асинхронного общения и внести вклад в обмен знаниями в команде.
Доверьтесь асинхронной связи
Пандемия положила начало периоду самоизоляции, и многие из нас теперь работают из дома. Благодаря этому эффективная асинхронная связь стала первостепенной задачей. В дополнение к email и мессенджерам, проверка пулл-реквестов является вариантом асинхронного общения. У асинхронного общения есть свои преимущества:
- Люди из разных часовых поясов могут чувствовать себя вовлеченными.
- Удобно для людей с разным знанием языка (человеческого, а не языка программирования).
- Обеспечивает гибкость для людей с разными графиками.
Разработка надёжной стратегии асинхронной коммуникации, особенно в отношении обзоров кода, требует двух вещей: доверия и стандартов. Не имея возможности наблюдать за выражением лица и интонацией голоса собеседника, остаётся доверять его благим намерениям при получении отзывов.
А стандарты код-ревью помогут уменьшить трения, связанные с двусмысленностью. Например, разъяснение того, какой отзыв является придиркой, а какой отзыв фактически блокирует слияние, помогает прояснить ожидания для всех, кто участвует в процессе проверки. Этих проблем можно избежать, выделив время всей командой для определения стандартов.
Ещё есть документация. Очень сложно подготовить хорошую документацию для проектов, особенно если нет специального технического писателя. Обратите внимание на пассивную документацию: способы обмена информацией без активного участия, т.е. все виды артефактов, которые команды создают, когда они исследуют, проектируют и создают продукт публично. Пассивная документация включает письменный диалог для исследования ошибки или описания пулл-реквестов. Да, «пассивные документы» сложнее искать, если у них нет специального оглавления или маркировки, но они обеспечивают удобный формат для обмена знаниями.
Позвольте автоматизации оптимизировать процессы
Иногда требуется машина, чтобы помочь людям не мешать друг другу, когда дело касается совместной работы. Создание GitHub Actions и подобных ему сервисов позволило легко внедрять автоматические проверки в процесс обзора кода. Но здесь возникает и большая ответственность. Какие проверки целесообразно автоматизировать? Стратегия может быть примерно такая:
1. Меньше значит больше. Из-за множества проверок любому, кто занимается код-ревью, может быть очень сложно отличить, что важно, а что нет. Автоматизация при консервативном применении может помочь сфокусироваться на важных вещах. Но излишняя автоматизация проверки может сбивать с толку и демотивировать в принятии решений.
2. Автоматизация как второй мозг. Автоматизация должна помогать там, где человеческое внимание может подвести. Автоматизируйте проверки качества кода, что облегчит жизнь разработчикам, дав им возможность сосредоточиться на проверках на более высоких уровнях, а также на обмене знаниями.
3. Автоматизация должна расширять возможности людей. Эффективная автоматизация должна позволять людям полностью владеть определёнными функциями. Например, автоматическое перемещение пулл-реквеста в ишью, при получении отзыва, пометка его и назначение его исполнителю даст команде больше понимания того, кто владеет какими функциональными областями. Вместо того, чтобы отправлять задачу в общую кучу невыполненной работы, автоматизация поможет поддерживать действенность обратной связи.
Итого
Хотя проверка кода часто считается утомительной, она может стать благодатной почвой для роста эмпатии, более активного общения и лучшего обмена знаниями внутри команд. А даже небольшая автоматизация может иметь большое значение.
Источник: https://github.com/readme/guides/code-review-optimization
Как Оптимизировать Обзоры Кода
Обзоры кода требуют значительных временных затрат, и важно понять, как инженеры могут извлечь из них максимальную пользу. Процесс проверки кода (с помощью некоторой автоматизации) может быть идеальной возможностью для членов команд развить навыки асинхронного общения и внести вклад в обмен знаниями в команде.
Доверьтесь асинхронной связи
Пандемия положила начало периоду самоизоляции, и многие из нас теперь работают из дома. Благодаря этому эффективная асинхронная связь стала первостепенной задачей. В дополнение к email и мессенджерам, проверка пулл-реквестов является вариантом асинхронного общения. У асинхронного общения есть свои преимущества:
- Люди из разных часовых поясов могут чувствовать себя вовлеченными.
- Удобно для людей с разным знанием языка (человеческого, а не языка программирования).
- Обеспечивает гибкость для людей с разными графиками.
Разработка надёжной стратегии асинхронной коммуникации, особенно в отношении обзоров кода, требует двух вещей: доверия и стандартов. Не имея возможности наблюдать за выражением лица и интонацией голоса собеседника, остаётся доверять его благим намерениям при получении отзывов.
А стандарты код-ревью помогут уменьшить трения, связанные с двусмысленностью. Например, разъяснение того, какой отзыв является придиркой, а какой отзыв фактически блокирует слияние, помогает прояснить ожидания для всех, кто участвует в процессе проверки. Этих проблем можно избежать, выделив время всей командой для определения стандартов.
Ещё есть документация. Очень сложно подготовить хорошую документацию для проектов, особенно если нет специального технического писателя. Обратите внимание на пассивную документацию: способы обмена информацией без активного участия, т.е. все виды артефактов, которые команды создают, когда они исследуют, проектируют и создают продукт публично. Пассивная документация включает письменный диалог для исследования ошибки или описания пулл-реквестов. Да, «пассивные документы» сложнее искать, если у них нет специального оглавления или маркировки, но они обеспечивают удобный формат для обмена знаниями.
Позвольте автоматизации оптимизировать процессы
Иногда требуется машина, чтобы помочь людям не мешать друг другу, когда дело касается совместной работы. Создание GitHub Actions и подобных ему сервисов позволило легко внедрять автоматические проверки в процесс обзора кода. Но здесь возникает и большая ответственность. Какие проверки целесообразно автоматизировать? Стратегия может быть примерно такая:
1. Меньше значит больше. Из-за множества проверок любому, кто занимается код-ревью, может быть очень сложно отличить, что важно, а что нет. Автоматизация при консервативном применении может помочь сфокусироваться на важных вещах. Но излишняя автоматизация проверки может сбивать с толку и демотивировать в принятии решений.
2. Автоматизация как второй мозг. Автоматизация должна помогать там, где человеческое внимание может подвести. Автоматизируйте проверки качества кода, что облегчит жизнь разработчикам, дав им возможность сосредоточиться на проверках на более высоких уровнях, а также на обмене знаниями.
3. Автоматизация должна расширять возможности людей. Эффективная автоматизация должна позволять людям полностью владеть определёнными функциями. Например, автоматическое перемещение пулл-реквеста в ишью, при получении отзыва, пометка его и назначение его исполнителю даст команде больше понимания того, кто владеет какими функциональными областями. Вместо того, чтобы отправлять задачу в общую кучу невыполненной работы, автоматизация поможет поддерживать действенность обратной связи.
Итого
Хотя проверка кода часто считается утомительной, она может стать благодатной почвой для роста эмпатии, более активного общения и лучшего обмена знаниями внутри команд. А даже небольшая автоматизация может иметь большое значение.
Источник: https://github.com/readme/guides/code-review-optimization
👍7