code-quality

Acerca de la calidad del código

code-quality es una referencia concisa sobre convenciones de codificación para el proyecto de base de datos Turso (Limbo), que recoge las reglas de corrección, los patrones típicos de Rust y las pautas de comentarios y prevención del sobrediseño que los colaboradores deben aplicar siempre que escriban código. Su principio rector es que se trata de una base de datos en producción donde la corrección es primordial y es preferible un cierre inesperado antes que la corrupción de datos, por lo que codifica los hábitos que mantienen segura la base de código.

La guía establece reglas de corrección (sin soluciones temporales ni trucos rápidos, usar assert con frecuencia, provocar cierre en estados inválidos que puedan poner en riesgo la integridad de los datos, considerar casos límite) y patrones de Rust (hacer que los estados ilegales no sean representables, utilizar coincidencias exhaustivas de patrones, preferir enums a cadenas o sentinels, minimizar las asignaciones en el heap, escribir código optimizado para la CPU). Ofrece orientación concreta sobre instrucciones if: usar assert!, devolver un error o unreachable! para ramas que nunca deberían ejecutarse en lugar de ignorarlas silenciosamente, además de reglas de comentarios que fomentan documentar el porqué en lugar del qué, prohibiendo referencias a conversaciones con IA y marcadores temporales. También advierte sobre la necesidad de verificar cuidadosamente el orden de las mutaciones de índices frente a SQLite para evitar incoherencias, señala una habilidad relacionada con modelos de E/S asíncrona y enumera reglas de limpieza para no dejar código obsoleto ni soluciones retrocompatibles.

Está dirigida a los colaboradores de la base de código Rust Turso/Limbo y, de forma más general, a cualquier persona que escriba en Rust a nivel de sistema y busque una lista compacta de verificación de corrección. Se trata de documentación puramente orientativa: no contiene scripts, comandos, credenciales ni efectos secundarios, por lo que es completamente inocua.

Preguntas frecuentes

¿Cuál es el principio fundamental?

Se trata de una base de datos en producción donde la corrección es primordial, por lo que es preferible un cierre inesperado antes que la corrupción de datos. Las reglas buscan que se produzca un error evidente en lugar de continuar en un estado indefinido.

¿Cómo debo manejar las ramas que nunca deberían ocurrir?

No las ignore silenciosamente. Use assert! con un mensaje que indique la invariante, devuelva un error o utilice unreachable!; reserve los simples if/else para casos en los que ambas ramas son rutas esperadas.

¿Cuáles son las reglas de comentarios?

Documente el porqué en lugar del qué, documente funciones/estructuras/enums/variantes y evite comentarios que repitan código, hagan referencia a conversaciones con IA o contengan marcadores temporales como “added” o “Phase 1”.

¿Se aplica más allá de Turso?

Está escrita para la base de código Rust Turso/Limbo, pero sus orientaciones sobre corrección y patrones de Rust son útiles en general para el trabajo con Rust a nivel de sistema.

¿Por qué se mencionan las mutaciones de índices?

Porque el orden de inserción, eliminación y resolución de conflictos debe coincidir con SQLite; un orden incorrecto provoca incoherencias en los índices que son fáciles de pasar por alto.