Introduction
Un code qui fonctionne n'est qu'une partie d'un projet qu'une autre personne peut maintenir en toute sécurité. Une crate Rust prête à être transmise doit également respecter un formatage cohérent, éviter les constructions suspectes, expliquer son interface publique et conserver des tests réussis.
Dans ce lab, vous allez réparer une petite bibliothèque à l'aide des outils de projet standard de Rust. Vous utiliserez successivement rustfmt, Clippy et rustdoc, puis vous les combinerez avec la suite de tests pour former une boucle de qualité reproductible. Le code est volontairement réduit afin que vous puissiez vous concentrer sur ce que chaque outil vérifie.
Formater le code source de manière cohérente
Dans cette étape, vous allez utiliser rustfmt pour détecter et corriger les différences de mise en forme sans modifier le comportement du programme.
Accédez à la bibliothèque préparée et ouvrez son code source :
cd /home/labex/project/handoff-helpers
nano src/lib.rs
La première fonction est du Rust valide, mais ses espaces et son indentation diffèrent du reste du fichier. Les règles de formatage sont mécaniques : un outil peut donc les appliquer de manière plus fiable que chaque contributeur ne pourrait le faire manuellement. Appuyez sur Ctrl+X sans modifier le fichier.
Commencez par utiliser le mode de vérification :
cargo fmt -- --check
Cette commande doit échouer et afficher un diff. cargo fmt sélectionne les fichiers Rust du package. Le premier -- termine les options de Cargo, et le second --check est transmis à rustfmt. Le mode de vérification signale les différences sans réécrire le fichier ; il est donc utile dans les contrôles automatisés.
Appliquez maintenant le formateur :
cargo fmt
Ouvrez de nouveau le code source :
nano src/lib.rs
La première fonction présente maintenant des espaces, des retours à la ligne et une indentation cohérents. Ses noms et sa logique n'ont pas changé. Quittez nano et vérifiez que le mode de vérification ne produit plus de sortie :
cargo fmt -- --check
L'absence de sortie et un code de retour indiquant la réussite signifient que tous les fichiers Rust respectent déjà les règles de rustfmt.
Corriger les avertissements de Clippy
Dans cette étape, vous allez utiliser Clippy pour repérer du code qui se compile, mais dont l'intention peut être exprimée plus clairement.
Le compilateur Rust vérifie que le code est valide et respecte les types. Clippy ajoute des lints pour détecter les constructions suspectes, inutilement complexes ou non idiomatiques. Exécutez-le en transformant les avertissements en erreurs :
cargo clippy -- -D warnings
Cette première exécution doit échouer. Comme avec rustfmt, -- transmet l'option restante à l'outil sous-jacent. -D warnings signifie deny warnings : le contrôle de qualité se termine avec un code différent de zéro tant que tous les avertissements signalés ne sont pas corrigés.
Clippy signale deux améliorations ciblées : utiliser la méthode directe de vérification du vide plutôt que de comparer une longueur à zéro, et accepter une slice au lieu d'exiger que les appelants possèdent un Vec. Ouvrez le code source :
nano src/lib.rs
Remplacez :
if cleaned.len() == 0 {
par :
if cleaned.is_empty() {
Modifiez ensuite le paramètre open_count de :
tasks: &Vec<bool>
en :
tasks: &[bool]
is_empty() exprime directement la question posée. Une slice accepte des données de séquence empruntées sans imposer inutilement le conteneur concret Vec. Enregistrez le fichier et quittez nano, formatez cette petite modification, puis relancez Clippy :
cargo fmt
cargo clippy -- -D warnings
Une dernière ligne Finished, sans avertissement, prouve que la bibliothèque se compile proprement avec cette politique de lint plus stricte.
Documenter l'interface publique
Dans cette étape, vous allez ajouter des commentaires de documentation et générer une documentation d'API consultable.
Les commentaires commençant par /// documentent l'élément qui les suit immédiatement. Les commentaires commençant par //! décrivent la crate ou le module qui les contient. Rustdoc transforme ces deux formes en documentation HTML reliée.
Ouvrez le code source de la bibliothèque :
nano src/lib.rs
Ajoutez ces deux lignes tout en haut du fichier :
//! Small helpers for preparing task data for reports.
#![deny(missing_docs)]
Cet attribut interne transforme l'absence de documentation sur les éléments publics en erreur de compilation. La documentation devient ainsi une règle explicite du projet plutôt qu'une simple recommandation.
Ajoutez ce commentaire immédiatement au-dessus de normalize_title :
/// Returns a trimmed title, or `Untitled` when the input is blank.
Ajoutez ce commentaire immédiatement au-dessus de open_count :
/// Counts entries whose completion value is `false`.
Enregistrez le fichier et quittez nano. Générez la documentation pour ce package uniquement :
cargo doc --no-deps
cargo doc exécute rustdoc. L'option --no-deps ignore la documentation des crates dépendantes, afin de cibler le résultat sur ce package et d'accélérer la génération. La page d'entrée générée est target/doc/handoff_helpers/index.html ; Cargo remplace le trait d'union du nom du package par un underscore dans le nom de la crate Rust.
ls target/doc/handoff_helpers/index.html
Si ce chemin s'affiche, cela prouve que rustdoc a généré la page de la crate et que la règle concernant les éléments non documentés a été respectée.
Exécuter la boucle de qualité complète
Dans cette étape, vous allez combiner les différents outils en une séquence prévisible à exécuter avant de transmettre le projet.
Le formatage, l'analyse statique, la documentation et les tests répondent à des questions différentes :
- rustfmt vérifie si le code source respecte la mise en forme standard ;
- Clippy vérifie s'il reste des constructions connues comme suspectes ou peu claires ;
- les tests vérifient si le comportement requis fonctionne toujours ;
- rustdoc vérifie si l'interface publique peut être documentée conformément à la règle du projet.
Exécutez chaque contrôle séparément afin qu'un échec indique clairement le point concerné. Commencez par le formatage :
cargo fmt -- --check
Exécutez l'analyse statique stricte :
cargo clippy -- -D warnings
Lancez les tests de la bibliothèque :
cargo test
La sortie doit indiquer que deux tests ont réussi. Régénérez enfin la documentation ciblée :
cargo doc --no-deps
Lorsque les quatre commandes réussissent dans cet ordre, la crate est formatée de manière cohérente, exempte d'avertissements Clippy, testée au niveau comportemental et documentée. Exécuter la même boucle avant de transmettre le projet transforme la qualité en preuve reproductible, plutôt qu'en simple impression visuelle finale.
Résumé
Vous avez corrigé le formatage avec rustfmt, résolu les problèmes stricts signalés par Clippy, documenté l'interface publique d'une bibliothèque, généré la documentation rustdoc et conservé des tests réussis. Plus important encore, vous avez combiné ces outils en une boucle de qualité reproductible qui peut contribuer à une transmission fiable du projet.
