Einführung
Funktionierender Code ist nur ein Teil eines Projekts, das eine andere Person sicher warten können soll. Eine für die Übergabe geeignete Rust-Crate sollte außerdem einheitlich formatiert sein, verdächtige Muster vermeiden, ihre öffentliche Schnittstelle erklären und ihre Tests erfolgreich ausführen.
In diesem Lab reparieren Sie eine kleine Bibliothek mit den Standardwerkzeugen von Rust für Projekte. Sie führen rustfmt, Clippy und rustdoc nacheinander ein und kombinieren sie anschließend mit der Testsuite zu einer wiederholbaren Qualitätsschleife. Der Code ist absichtlich klein, damit Sie sich darauf konzentrieren können, was jedes Werkzeug überprüft.
Quellcode einheitlich formatieren
In diesem Schritt verwenden Sie rustfmt, um Unterschiede im Layout zu erkennen und zu beheben, ohne das Verhalten des Programms zu ändern.
Wechseln Sie in die vorbereitete Bibliothek und öffnen Sie den Quellcode:
cd /home/labex/project/handoff-helpers
nano src/lib.rs
Die erste Funktion ist gültiger Rust-Code, aber ihre Leerzeichen und Einrückungen unterscheiden sich vom restlichen Inhalt der Datei. Formatierungsregeln sind mechanisch. Ein Werkzeug kann sie daher zuverlässiger anwenden, als wenn jede mitwirkende Person dies von Hand erledigt. Drücken Sie Strg+X, ohne Änderungen vorzunehmen.
Verwenden Sie zunächst den Prüfmodus:
cargo fmt -- --check
Dieser Befehl sollte fehlschlagen und einen Diff anzeigen. cargo fmt wählt die Rust-Dateien des Pakets aus. Das erste -- beendet die Optionen von Cargo, und das zweite --check wird an rustfmt weitergegeben. Der Prüfmodus meldet Unterschiede, schreibt die Datei aber nicht neu. Dadurch eignet er sich für automatisierte Prüfungen.
Wenden Sie nun den Formatierer an:
cargo fmt
Öffnen Sie den Quellcode erneut:
nano src/lib.rs
Die erste Funktion hat jetzt einheitliche Leerzeichen, Zeilenumbrüche und Einrückungen. Ihre Namen und ihre Logik sind unverändert. Beenden Sie nano und stellen Sie sicher, dass der Prüfmodus keine Ausgabe mehr erzeugt:
cargo fmt -- --check
Keine Ausgabe und ein erfolgreicher Abschluss bedeuten, dass bereits jede Rust-Datei den Regeln von rustfmt entspricht.
Clippy-Warnungen beheben
In diesem Schritt verwenden Sie Clippy, um Code zu finden, der zwar kompiliert, seine Absicht aber klarer ausdrücken kann.
Der Rust-Compiler prüft, ob der Code gültig und typsicher ist. Clippy ergänzt Lints für verdächtige, unnötig komplexe oder nicht idiomatische Muster. Führen Sie Clippy mit Warnungen aus, die als Fehler behandelt werden:
cargo clippy -- -D warnings
Dieser erste Durchlauf sollte fehlschlagen. Wie bei rustfmt übergibt -- die verbleibende Option an das zugrunde liegende Werkzeug. -D warnings bedeutet deny warnings. Die Qualitätsprüfung wird daher mit einem Fehlercode beendet, solange noch eine gemeldete Warnung behoben werden muss.
Clippy weist auf zwei konkrete Verbesserungen hin: Verwenden Sie die direkte Methode zur Prüfung auf Leere, statt eine Länge mit null zu vergleichen, und akzeptieren Sie einen Slice, statt von den Aufrufern den Besitz eines Vec zu verlangen. Öffnen Sie den Quellcode:
nano src/lib.rs
Ändern Sie:
if cleaned.len() == 0 {
in:
if cleaned.is_empty() {
Ändern Sie anschließend den Parameter tasks von:
tasks: &Vec<bool>
in:
tasks: &[bool]
is_empty() formuliert die Frage direkt. Ein Slice akzeptiert geliehene Sequenzdaten, ohne unnötigerweise den konkreten Vektor-Container zu verlangen. Speichern Sie die Datei und beenden Sie nano. Formatieren Sie anschließend die kleine Änderung und führen Sie Clippy erneut aus:
cargo fmt
cargo clippy -- -D warnings
Eine abschließende Zeile mit Finished und ohne Warnungen zeigt, dass die Bibliothek unter der strengeren Lint-Richtlinie fehlerfrei kompiliert.
Die öffentliche Schnittstelle dokumentieren
In diesem Schritt fügen Sie Dokumentationskommentare hinzu und erzeugen durchsuchbare API-Dokumentation.
Kommentare, die mit /// beginnen, dokumentieren das unmittelbar darunter stehende Element. Kommentare, die mit //! beginnen, beschreiben die umgebende Crate oder das umgebende Modul. Rustdoc wandelt beide Formen in verknüpfte HTML-Dokumentation um.
Öffnen Sie den Quellcode der Bibliothek:
nano src/lib.rs
Fügen Sie diese beiden Zeilen ganz oben ein:
//! Small helpers for preparing task data for reports.
#![deny(missing_docs)]
Das innere Attribut macht fehlende Dokumentation bei öffentlichen Elementen zu einem Build-Fehler. Dadurch wird Dokumentation von einer Empfehlung zu einer ausdrücklichen Projektrichtlinie.
Fügen Sie diesen Kommentar unmittelbar über normalize_title ein:
/// Returns a trimmed title, or `Untitled` when the input is blank.
Fügen Sie diesen Kommentar unmittelbar über open_count ein:
/// Counts entries whose completion value is `false`.
Speichern Sie die Datei und beenden Sie nano. Erzeugen Sie die Dokumentation nur für dieses Paket:
cargo doc --no-deps
cargo doc führt rustdoc aus. Die Option --no-deps überspringt die Dokumentation abhängiger Crates. Dadurch bleibt das Ergebnis fokussiert und wird schneller erzeugt. Die erzeugte Einstiegsseite befindet sich unter target/doc/handoff_helpers/index.html; Cargo ersetzt den Bindestrich des Paketnamens durch einen Unterstrich im Namen der Rust-Crate.
ls target/doc/handoff_helpers/index.html
Wenn dieser Pfad angezeigt wird, hat rustdoc die Seite der Crate erzeugt und die Richtlinie für fehlende Dokumentation wurde erfüllt.
Die vollständige Qualitätsschleife ausführen
In diesem Schritt kombinieren Sie die einzelnen Werkzeuge zu einer verlässlichen Abfolge vor der Übergabe.
Formatierung, Linting, Dokumentation und Tests beantworten unterschiedliche Fragen:
- rustfmt prüft, ob der Quellcode dem Standard-Layout entspricht;
- Clippy prüft, ob bekannte verdächtige oder unklare Muster verbleiben;
- Tests prüfen, ob das erforderliche Verhalten weiterhin funktioniert;
- rustdoc prüft, ob die öffentliche Schnittstelle gemäß der Projektrichtlinie dokumentiert werden kann.
Führen Sie jede Prüfung separat aus, damit ein Fehler eindeutig einem Bereich zugeordnet werden kann. Beginnen Sie mit der Formatierung:
cargo fmt -- --check
Führen Sie das strenge Linting aus:
cargo clippy -- -D warnings
Führen Sie die Bibliothekstests aus:
cargo test
Die Ausgabe sollte zwei erfolgreiche Tests melden. Erzeugen Sie abschließend erneut die fokussierte Dokumentation:
cargo doc --no-deps
Wenn alle vier Befehle in dieser Reihenfolge erfolgreich sind, ist die Crate einheitlich formatiert, lint-frei, durch Tests auf ihr Verhalten geprüft und dokumentiert. Wenn Sie dieselbe Schleife vor der Übergabe ausführen, wird Qualität zu wiederholbaren Nachweisen statt zu einer abschließenden visuellen Vermutung.
Zusammenfassung
Sie haben die Formatierung mit rustfmt repariert, die strengen Clippy-Meldungen behoben, eine öffentliche Bibliotheksschnittstelle dokumentiert, eine rustdoc-Ausgabe erzeugt und die Tests erfolgreich ausgeführt. Noch wichtiger ist, dass Sie diese Werkzeuge zu einer wiederholbaren Qualitätsschleife kombiniert haben, die eine zuverlässige Projektübergabe unterstützt.
