Как разработчики, мы все слишком хорошо знакомы с обзорами кода. Иметь еще одну пару глаз, чтобы взглянуть на наш код, может быть чудесно; это показывает нам так много аспектов нашего кода, которые мы не заметили бы иначе. Обзор кода может быть информативным, а может быть и познавательным. Я могу с уверенностью отнести большую часть того, что я знаю о хороших методах программирования, к обзорам кода.
Объем обучения, который обзор отнимает у обзора кода, зависит от того, насколько хорошо он выполняется. Таким образом, на рецензента ложится ответственность за то, чтобы его рецензия была учтена, упаковав в нее как можно больше уроков.
Это руководство по некоторым жизненно важным аспектам кода, которые вы должны проверять в своих обзорах, ожиданиям, которые вы должны иметь от этих проверок, и некоторым идеям о том, как инструменты (такие как линтеры, форматтеры и наборы тестов) могут помочь оптимизировать процесс.
Контрольный список проверки кода
Мы сформулировали это руководство в виде контрольного списка. В нем перечислен набор вопросов, которые вы должны задать о коде. Если ответ на любой из них не является “да”, вы должны оставить замечание о пиаре.
Обратите внимание, что этот список предназначен только для того, чтобы служить ориентиром. Ваша кодовая база, как и любая кодовая база, имеет свой собственный специфический набор потребностей, поэтому не стесняйтесь опираться на это руководство и переопределять его части, которые плохо подходят для ваших вариантов использования.
Этикет
Первое и самое главное, что нужно проверить во время обзора, – это насколько точно PR придерживается основных этикетов. Хорошие PR состоят из изменений размера укуса и решают единственную четко определенную проблему. Они должны быть сфокусированы и целенаправленно сужены, чтобы иметь как можно меньше конфликтов слияния. Проще говоря, хорошая ЦЕНА облегчает пересмотр.
Для крупномасштабных пикирующих изменений создайте отдельную целевую ветвь, а затем сделайте небольшие инкрементные PR-запросы к этой цели, окончательно объединив цель с основной ветвью. Создание одного огромного пиара затрудняет его обзор, и если он устареет, может возникнуть много конфликтов слияния.
При рассмотрении PR-сообщений от новых разработчиков я также стараюсь убедиться, что их сообщения о фиксации хорошо написаны .
Контрольный список:
- Является ли PR атомарным?
- Следует ли PR принципу единой заботы?
- Хорошо ли написаны сообщения о фиксации?
Идеи:
Примените формат сообщения фиксации в команде. Например, вы можете попробовать gifmoji , где вы используете emoji в сообщениях фиксации. Например, исправления ошибок должны начинаться с [FIX] , или 🐛 emoji и новые функции должны начинаться с [FEAT] или ✨ emoji. Это делает намерение совершить очень ясным.
Функциональность и синтаксис
Следующее, что нужно проверить, – эффективен ли PR в том, что он работает. Код, измененный PR, должен работать так, как ожидалось. Исправление ошибки должно решить проблему, которую оно должно было исправить. Функция должна обеспечивать необходимую дополнительную функциональность, не нарушая ничего другого.
Важно иметь в виду, что любая новая функция, добавленная aPR, оправдана. Простой способ убедиться в этом-принять только те PR, которые связаны с уже отсортированной проблемой. Эта практика сводит к минимуму feature-creep .
Контрольный список:
- Работает ли пиар?
- Добавляет ли новая функция ценность или это признак ползучести функции?
- Добавляет ли PR тест-кейсы для модифицированного кода?
Идеи:
Наличие комплексных тестов в коде облегчает проверку того, что новая функциональность работает, и затрудняет для PRs ломку существующих вещей. Та часть кода, о которой идет речь, никогда не должна попадать в PR. Любой новый код должен иметь полный охват в модульных/функциональных тестах. Python поставляется с надежной платформой модульного тестирования встроенной в сам язык. Вы должны использовать его в своей кодовой базе.
Дизайн
После того, как мы установили, что код работает, следующий шаг-проверить, насколько хорошо он интегрируется с существующей кодовой базой. Одна из ключевых вещей, которую следует проверить в этом отношении, – это дублирование. Часто код, добавляемый в репо, предоставляет функциональность, которая уже может быть частью кода в другом месте или чем-то предоставленным используемыми фреймворками или пакетами Pip. Это знание-то, что человек может получить только через опыт. Как старший, вы обязаны указывать на такое дублирование новым разработчикам, вносящим свой вклад в ваше репо.
Внимание к парадигмам также необходимо. Многие проекты имеют заранее принятые парадигмы проектирования, такие как микросервисы, монорепо или облачные технологии. Любой входящий код должен соответствовать этим парадигмам.
Контрольный список:
- Правильно ли спланирован и разработан код?
- Будет ли код хорошо работать с существующим кодом и не увеличит дублирование?
- Хорошо ли организован код с точки зрения размещения компонентов?
Паттерны и идиомы
Python-очень зрелый язык. Он управляется на основе определенных философий, описанных как Дзен Питона . Эти философии породили множество условностей и идиом, которым, как ожидается, будет следовать новый кодекс.
Разница между идиоматическим и неидиоматическим кодом очень тонка и в большинстве случаев может быть измерена только интуитивно. Как и все вещи, отточенные опытом, интуиция должна передаваться от опытных людей, таких как вы, к новичкам, таким как ваши ревьюи.
Контрольный список:
- Соответствует ли код идиомам и кодовым шаблонам языка?
- Использует ли код языковые функции и стандартные библиотеки?
Идеи:
Большинство линтеров, в народе PyLint , может помочь вам выявить отклонения от руководств по стилю и, в большинстве случаев, даже автоматически исправить их. Линтеры работают невероятно быстро и могут вносить исправления в код в режиме реального времени, что делает их ценным дополнением к вашей цепочке инструментов.
Читабельность
Python широко рассматривается как очень читаемый язык. Простота синтаксиса Python и сокращение использования знаков препинания в значительной степени способствуют его удобочитаемости. Имеет смысл только для того, чтобы код, написанный на этом языке, был также читаем. Контрольный список:
- Является ли код ясным и кратким?
- Соответствует ли он PEP-8?
- Соблюдаются ли все языковые и проектные соглашения?
- Даны ли идентификаторам значимые и совместимые с руководством по стилю имена?
Идеи:
Хороший форматер кода, такой как Черный может очень помочь в форматировании кода для обеспечения согласованности и читабельности. Черный цвет также предлагает минимальную настройку, что хорошо, потому что он устраняет все формы bikeshedding .
Мы уже говорили о том, что интеграция Black в ваш конвейер CI может творить чудеса во время проверки кода.
Документация и ремонтопригодность
Следующее, что нужно проверить, – это ремонтопригодность кода. Любой код, добавленный или измененный PR, должен быть написан для того, чтобы помочь кому-то, кроме оригинального автора, поддерживать его.
Желательно, чтобы он был самодокументирован, то есть написан таким образом, чтобы любой читающий код мог понять, что он делает. Это один из отличительных признаков хорошего кода Python. Если код должен быть сложным по замыслу, он должен быть достаточно документирован. В идеальном мире все классы и функции имели бы Python docstrings, дополненные примерами.
Контрольный список:
- Является ли код самодокументированным или хорошо документированным?
- Свободен ли код от запутывания и ненужной сложности?
- Понятна ли взаимосвязь потока управления и компонентов?
Идеи:
Sphinx – это генератор документации, который экспортирует красивую документацию из Python docstrings. Затем экспортированная документация может быть загружена в ReadTheDocs , популярный инструмент для размещения документов. Сфинкс-одна из главных причин, почему я так люблю писать документацию.
Безопасность
Обеспечение того, чтобы приложение оставалось безопасным, имеет решающее значение. Следующее, что нужно проверить, – это поддерживает ли PR или улучшает безопасность проекта. Вы должны убедиться, что изменения не увеличивают площадь поверхности атаки и не обнаруживают уязвимостей. Если PR добавляет новые зависимости, они потенциально могут быть небезопасны, и в этом случае вам может потребоваться проверить версию на наличие известных эксплойтов и при необходимости обновить зависимости.
Контрольный список:
- Свободен ли код от ошибок реализации, которые могут быть использованы?
- Были ли все новые зависимости проверены на наличие уязвимостей?
Идеи:
Одним из известных анализаторов безопасности для Python является Bandit . Кроме того, если вы используете GitHub для размещения кода, вы должны обязательно прочитать это руководство о настройке обнаружения уязвимостей и Dependabot для вашей кодовой базы.
Как только вы настроите обнаружение уязвимостей на GitHub, вы получите такие уведомления…
… с подробными сведениями об уязвимости и PR в ваших репозиториях, которые вы можете объединить, чтобы исправить их.
Мы также недавно говорили о распространенных ловушках безопасности в Python разработке и о том, как вы можете защитить свои проекты от них.
Производительность, надежность и масштабируемость
Последнее, что нужно проверить, – это производительность и надежность кода в масштабе. Хотя это, несомненно, ключевые показатели, я помещаю их в нижнюю часть контрольного списка, потому что считаю, что хорошо спланированный, хорошо разработанный и хорошо написанный код, как правило, тоже хорошо работает.
Контрольный список:
- Оптимизирован ли код с точки зрения временной и пространственной сложности?
- Масштабируется ли он в соответствии с потребностью?
- Есть ли у него такие инструменты, как отчетность по метрикам и оповещение о сбоях?
Идеи:
Отличный способ добавить некоторую надежность Python-это использовать подсказки типов и статическую проверку типов, которые могут дать подсказки о возможных ошибках перед выполнением. Python new native support for type-hints в первую очередь вдохновлен синтаксисом Mypy , который может быть постепенно принят в существующих проектах.
Глубокий Источник
Deep Source-это автоматизированный инструмент проверки кода, который управляет сквозным процессом сканирования кода и автоматически делает запросы на вытягивание с исправлениями всякий раз, когда выдвигаются новые коммиты или новые запросы на вытягивание.
Настройка Deep Source для Python – это быстрый, простой и бесшумный процесс. Просто добавьте файл .deep source.toml в корень репо, и сразу же Deep Source заберет его для сканирования. Сканирование найдет область для улучшений в вашей кодовой базе, внесет эти улучшения и откроет запросы на вытягивание найденных изменений. Я был поражен простотой настройки и эффективностью их самодельного кодового движка.
🙋 ♂ ️/| Trivia: Знаете ли вы, что DeepSource имеет честь быть в кураторском списке OWASP/| инструментов анализа исходного кода для Python?
Идеальный обзор кода
Возвращаясь к моей точке зрения о том, что обзоры кода являются образовательными и информативными, я также хотел бы добавить, что обзоры кода отнимают много времени и ресурсов. Хотя каждый обзор требует времени, более глубокие и всесторонние потребляют еще больше.
Поэтому каждый обзор должен быть максимально продуктивным. Именно на это должны быть направлены все усилия по оснастке и автоматизации. Автоматизируя все, что может быть автоматизировано, а это, как правило, обычные части обзора, такие как стиль кода и форматирование, мы можем позволить разработчикам сосредоточиться на таких важных вещах, как архитектура, дизайн и масштабируемость.
Я оставлю вас с глубокой мыслью, которой поделился со мной мой наставник.
Хороший обзор кода улучшает не только код, но и кодировщика.
Первоначально опубликовано в Deep Source Blog .