Introducción
El código que funciona es solo una parte de un proyecto que otra persona pueda mantener de forma segura. Un crate de Rust listo para entregar también debe usar un formato coherente, evitar patrones sospechosos, explicar su interfaz pública y mantener sus pruebas aprobadas.
En este laboratorio reparará una pequeña biblioteca con las herramientas estándar de proyectos de Rust. Introducirá rustfmt, Clippy y rustdoc de uno en uno, y después los combinará con el conjunto de pruebas para crear un ciclo de calidad repetible. El código es intencionadamente pequeño para que pueda concentrarse en lo que demuestra cada herramienta.
Formatee el código fuente de forma coherente
En este paso usará rustfmt para detectar y corregir diferencias de formato sin cambiar el comportamiento del programa.
Acceda a la biblioteca preparada y abra su código fuente:
cd /home/labex/project/handoff-helpers
nano src/lib.rs
La primera función es código Rust válido, pero sus espacios y sangría son diferentes de los del resto del archivo. Las reglas de formato son mecánicas, por lo que una herramienta puede aplicarlas con más fiabilidad que cada colaborador manualmente. Pulse Ctrl+X sin hacer cambios.
Primero use el modo de comprobación:
cargo fmt -- --check
Este comando debe fallar y mostrar una diferencia. cargo fmt selecciona los archivos Rust del paquete. El primer -- finaliza las opciones de Cargo, y el segundo --check se pasa a rustfmt. El modo de comprobación informa de las diferencias, pero no reescribe el archivo, por lo que resulta útil en comprobaciones automatizadas.
Ahora aplique el formateador:
cargo fmt
Abra de nuevo el código fuente:
nano src/lib.rs
La primera función ahora tiene espacios, saltos de línea y sangría coherentes. Sus nombres y su lógica no han cambiado. Salga de nano y confirme que el modo de comprobación no muestra nada:
cargo fmt -- --check
Ninguna salida y una terminación correcta indican que todos los archivos Rust ya cumplen las reglas de rustfmt.
Corrija las advertencias de Clippy
En este paso usará Clippy para encontrar código que compila, pero que puede expresar su intención con mayor claridad.
El compilador de Rust comprueba si el código es válido y seguro con respecto a los tipos. Clippy añade lints para detectar patrones sospechosos, innecesariamente complejos o poco idiomáticos. Ejecútelo tratando las advertencias como errores:
cargo clippy -- -D warnings
Esta primera ejecución debe fallar. Al igual que con rustfmt, -- pasa la opción restante a la herramienta subyacente. -D warnings significa denegar advertencias, por lo que la comprobación de calidad termina con un código distinto de cero hasta que se corrija cada advertencia indicada.
Clippy identifica dos mejoras concretas: usar el método directo para comprobar si una colección está vacía en lugar de comparar su longitud con cero, y aceptar un slice en lugar de exigir a quienes llaman a la función que posean un Vec. Abra el código fuente:
nano src/lib.rs
Cambie:
if cleaned.len() == 0 {
por:
if cleaned.is_empty() {
Después cambie el parámetro open_count de:
tasks: &Vec<bool>
a:
tasks: &[bool]
is_empty() expresa directamente la pregunta. Un slice acepta datos de una secuencia prestada sin exigir innecesariamente el contenedor concreto Vec. Guarde los cambios y salga de nano; después, dé formato a la pequeña modificación y vuelva a ejecutar Clippy:
cargo fmt
cargo clippy -- -D warnings
Una línea final Finished sin advertencias demuestra que la biblioteca compila correctamente con la política de lints más estricta.
Documente la interfaz pública
En este paso añadirá comentarios de documentación y generará documentación de la API que se pueda consultar en el navegador.
Los comentarios que comienzan con /// documentan el elemento que aparece inmediatamente después. Los comentarios que comienzan con //! describen el crate o módulo que los contiene. Rustdoc convierte ambas formas en documentación HTML enlazada.
Abra el código fuente de la biblioteca:
nano src/lib.rs
Añada estas dos líneas al principio del archivo:
//! Small helpers for preparing task data for reports.
#![deny(missing_docs)]
El atributo interno convierte la falta de documentación en los elementos públicos en un error de compilación. Así, la documentación deja de ser una sugerencia y pasa a ser una política explícita del proyecto.
Añada este comentario inmediatamente encima de normalize_title:
/// Returns a trimmed title, or `Untitled` when the input is blank.
Añada este comentario inmediatamente encima de open_count:
/// Counts entries whose completion value is `false`.
Guarde los cambios y salga de nano. Genere la documentación únicamente para este paquete:
cargo doc --no-deps
cargo doc ejecuta rustdoc. La opción --no-deps omite la documentación de los crates de dependencia, de modo que el resultado se concentra en este paquete y se genera más rápido. La página de entrada generada es target/doc/handoff_helpers/index.html; Cargo cambia el guion del nombre del paquete por un guion bajo en el nombre del crate de Rust.
ls target/doc/handoff_helpers/index.html
Si aparece esa ruta, significa que rustdoc generó la página del crate y que la política de documentación obligatoria se superó correctamente.
Ejecute el ciclo completo de calidad
En este paso combinará las herramientas individuales en una secuencia predecible antes de entregar el proyecto.
El formateo, el análisis estático, la documentación y las pruebas responden a preguntas diferentes:
- rustfmt comprueba si el código fuente tiene el formato estándar;
- Clippy comprueba si quedan patrones conocidos que sean sospechosos o poco claros;
- las pruebas comprueban si el comportamiento necesario sigue funcionando;
- rustdoc comprueba si la interfaz pública puede documentarse según la política del proyecto.
Ejecute cada comprobación por separado para que un fallo señale un límite concreto. Empiece por el formato:
cargo fmt -- --check
Ejecute el análisis estático estricto:
cargo clippy -- -D warnings
Ejecute las pruebas de la biblioteca:
cargo test
La salida debe indicar que se han aprobado dos pruebas. Por último, vuelva a generar la documentación específica:
cargo doc --no-deps
Cuando los cuatro comandos se ejecutan correctamente en este orden, el crate tiene un formato coherente, no contiene advertencias de Clippy, su comportamiento está probado y su documentación está generada. Ejecutar el mismo ciclo antes de entregar el proyecto convierte la calidad en evidencia repetible, en lugar de dejarla en una última comprobación visual.
Resumen
Reparó el formato con rustfmt, resolvió los hallazgos estrictos de Clippy, documentó la interfaz pública de una biblioteca, generó la salida de rustdoc y mantuvo las pruebas aprobadas. Más importante aún, combinó esas herramientas en un ciclo de calidad repetible que puede respaldar una entrega fiable del proyecto.
