Введение
Работающий код — лишь одна из составляющих проекта, который другой человек сможет безопасно сопровождать. Готовый к передаче crate Rust также должен использовать единообразное форматирование, избегать подозрительных конструкций, описывать свой публичный интерфейс и сохранять проходящие тесты.
В этой лабораторной работе вы исправите небольшую библиотеку с помощью стандартных инструментов Rust для работы с проектами. Вы по очереди познакомитесь с rustfmt, Clippy и rustdoc, а затем объедините их с набором тестов в повторяемый цикл контроля качества. Код намеренно небольшой, чтобы вы могли сосредоточиться на том, что именно проверяет каждый инструмент.
Единообразное форматирование исходного кода
На этом шаге вы используете rustfmt, чтобы обнаружить и исправить различия в оформлении кода, не изменяя поведение программы.
Перейдите в подготовленную библиотеку и откройте её исходный файл:
cd /home/labex/project/handoff-helpers
nano src/lib.rs
Первая функция написана на корректном Rust, но пробелы и отступы в ней отличаются от остального файла. Правила форматирования механические, поэтому инструмент применяет их надёжнее, чем каждый участник проекта вручную. Нажмите Ctrl+X, не внося изменений.
Сначала запустите проверку без изменения файла:
cargo fmt -- --check
Эта команда должна завершиться ошибкой и вывести различия. cargo fmt выбирает файлы Rust из пакета. Первый -- завершает обработку параметров Cargo, а второй --check передаётся инструменту rustfmt. Режим проверки показывает различия, но не перезаписывает файл, поэтому его удобно использовать в автоматических проверках.
Теперь примените форматирование:
cargo fmt
Снова откройте исходный файл:
nano src/lib.rs
У первой функции теперь единообразные пробелы, переносы строк и отступы. Её имена и логика не изменились. Выйдите из nano и убедитесь, что проверка завершается без вывода:
cargo fmt -- --check
Отсутствие вывода и успешное завершение команды означают, что все файлы Rust уже соответствуют правилам rustfmt.
Исправление предупреждений Clippy
На этом шаге вы используете Clippy, чтобы найти код, который компилируется, но может яснее выражать своё назначение.
Компилятор Rust проверяет корректность и безопасность типов в коде. Clippy добавляет линтеры для подозрительных, излишне сложных или неидиоматичных конструкций. Запустите его, превратив предупреждения в ошибки:
cargo clippy -- -D warnings
Этот первый запуск должен завершиться ошибкой. Как и в случае с rustfmt, -- передаёт оставшийся параметр нижележащему инструменту. -D warnings означает deny warnings — «запретить предупреждения», поэтому проверка завершается с ненулевым кодом, пока не будут исправлены все обнаруженные предупреждения.
Clippy предлагает два точечных улучшения: использовать прямой метод проверки пустоты вместо сравнения длины с нулём и принимать срез вместо требования владеть Vec. Откройте исходный файл:
nano src/lib.rs
Замените:
if cleaned.len() == 0 {
на:
if cleaned.is_empty() {
Затем измените параметр open_count с:
tasks: &Vec<bool>
на:
tasks: &[bool]
Метод is_empty() напрямую выражает проверяемое условие. Срез принимает заимствованные последовательности данных и не требует без необходимости конкретный контейнер Vec. Сохраните файл и выйдите из nano, отформатируйте небольшое изменение, а затем снова запустите Clippy:
cargo fmt
cargo clippy -- -D warnings
Итоговая строка Finished без предупреждений подтверждает, что библиотека успешно компилируется при строгой политике линтинга.
Документирование публичного интерфейса
На этом шаге вы добавите комментарии документации и сгенерируете просматриваемую документацию API.
Комментарии, начинающиеся с ///, документируют расположенный непосредственно под ними элемент. Комментарии, начинающиеся с //!, описывают содержащий их crate или модуль. Rustdoc преобразует оба вида комментариев в связанную HTML-документацию.
Откройте исходный файл библиотеки:
nano src/lib.rs
Добавьте эти две строки в самое начало файла:
//! Small helpers for preparing task data for reports.
#![deny(missing_docs)]
Внутренний атрибут превращает отсутствие документации у публичных элементов в ошибку сборки. Благодаря этому документирование становится не рекомендацией, а явным правилом проекта.
Добавьте следующий комментарий непосредственно перед normalize_title:
/// Returns a trimmed title, or `Untitled` when the input is blank.
Добавьте следующий комментарий непосредственно перед open_count:
/// Counts entries whose completion value is `false`.
Сохраните файл и выйдите из nano. Сгенерируйте документацию только для этого пакета:
cargo doc --no-deps
cargo doc запускает rustdoc. Параметр --no-deps пропускает документацию для пакетов-зависимостей, поэтому результат получается более целевым, а генерация — быстрее. Главная страница сгенерированной документации находится по пути target/doc/handoff_helpers/index.html; Cargo заменяет дефис в имени пакета на символ подчёркивания в имени crate Rust.
ls target/doc/handoff_helpers/index.html
Если этот путь отображается, значит rustdoc создал страницу crate, а политика обязательной документации прошла проверку.
Запуск полного цикла контроля качества
На этом шаге вы объедините отдельные инструменты в предсказуемую последовательность проверок перед передачей проекта.
Форматирование, линтинг, документация и тесты отвечают на разные вопросы:
- rustfmt проверяет, соответствует ли исходный код стандартному оформлению;
- Clippy проверяет, не остались ли известные подозрительные или неясные конструкции;
- тесты проверяют, продолжает ли работать требуемое поведение;
- rustdoc проверяет, можно ли документировать публичный интерфейс в соответствии с политикой проекта.
Запускайте каждую проверку отдельно, чтобы по ошибке можно было определить конкретную границу. Начните с форматирования:
cargo fmt -- --check
Запустите строгую проверку линтером:
cargo clippy -- -D warnings
Запустите тесты библиотеки:
cargo test
В выводе должны быть указаны два пройденных теста. Наконец, заново сгенерируйте целевую документацию:
cargo doc --no-deps
Если все четыре команды успешно выполняются в таком порядке, crate отформатирован единообразно, не содержит ошибок линтера, его поведение проверено тестами, а публичный интерфейс документирован. Повторение этого цикла перед передачей проекта превращает контроль качества в воспроизводимое подтверждение, а не в субъективную финальную проверку.
Итоги
Вы исправили форматирование с помощью rustfmt, устранили строгие замечания Clippy, задокументировали публичный интерфейс библиотеки, сгенерировали документацию rustdoc и сохранили проходящие тесты. Главное — вы объединили эти инструменты в повторяемый цикл контроля качества, который помогает надёжно передавать проект другому разработчику.
