English

Todo bloque unsafe necesita un comentario de seguridad

unsafe sin un comentario es solo un "confía en mí" en Rust. El bloque compila, las pruebas pasan, y lo único que lo mantiene correcto — el invariante que verificaste en tu cabeza — no está escrito en ninguna parte. Un revisor no puede confirmarlo. Un agente de IA que edite el archivo seis meses después no puede confirmarlo. La próxima refactorización rompe la suposición en silencio y obtienes comportamiento indefinido sin ninguna advertencia.

Por qué el comentario carga con el peso

Un bloque unsafe no desactiva la seguridad. Traslada la carga de la prueba del compilador hacia ti. Dentro de él puedes desreferenciar punteros crudos, llamar a otras funciones unsafe o acceder a un campo de una union — operaciones donde el compilador deja de verificar el contrato y confía en que tú ya lo hiciste. La regla que hace correcto al bloque (este índice está dentro de los límites, este puntero es no nulo y está alineado, este tiempo de vida sobrevive al préstamo) existe solo en tu cabeza hasta que la escribes.

Un comentario // SAFETY: la escribe. Convierte un "confía en mí" no verificable en una afirmación declarada que una persona o una herramienta puede revisar línea por línea.

La regla: sin comentario, no hay merge

Coloca un comentario // SAFETY: justo encima de cada bloque unsafe, nombrando el invariante del que depende el bloque y por qué se cumple aquí.

// SAFETY: `idx` is checked against `self.len` on the line above,
// so it is always in bounds for `get_unchecked`.
let elem = unsafe { self.data.get_unchecked(idx) };

La imagen espejo también importa: una sección # Safety en el comentario de documentación de toda función pública unsafe fn le dice a quien la llama qué debe garantizar antes de llamarla. El comentario SAFETY: salda esa obligación en el sitio de la llamada.

Aplícalo en CI, no en la revisión de código

No tienes que vigilar esto a mano. Clippy trae dos lints para ello:

• undocumented_unsafe_blocks — se activa ante cualquier bloque unsafe (o unsafe impl) sin un comentario // SAFETY: directamente encima.
• unnecessary_safety_comment (añadido en Rust 1.67.0) — el inverso: marca un comentario // SAFETY: adjunto a código que en realidad no es unsafe, para que los comentarios obsoletos no se pudran.

Convierte el primero en una barrera dura:

#![warn(clippy::undocumented_unsafe_blocks)]
// or, to block the merge outright:
#![deny(clippy::undocumented_unsafe_blocks)]

Combínalo con #![deny(unsafe_op_in_unsafe_fn)] — la política de la biblioteca estándar — para que el cuerpo de una unsafe fn no obtenga un pase libre: cada operación unsafe sigue necesitando su propio bloque unsafe, y por lo tanto su propio comentario. Así es exactamente como la biblioteca estándar de Rust aplica su política de comentarios de seguridad sobre decenas de miles de operaciones unsafe.

Por qué rinde con la IA en el circuito

Los revisores dejan de adivinar si un bloque es correcto y empiezan a verificarlo contra una regla escrita. También lo hacen los agentes de IA: dado el invariante declarado, un agente puede verificar que un cambio lo preserva, o rechazar la edición y señalar el riesgo — en lugar de borrar en silencio la verificación de límites que el comentario protegía discretamente. El comentario es el contrato legible por máquina que mantiene honestos tanto a las personas como a los modelos.

Recursos

• SAFETY comments — Rust Standard Library Developer Guide
• undocumented_unsafe_blocks — Clippy lint reference
• unnecessary_safety_comment — Clippy lint reference
• Meaning of unsafe — The Rustonomicon
• unsafe_op_in_unsafe_fn — The Rust Reference