code-quality

Sobre a qualidade do código

A code-quality é uma referência concisa de convenções de codificação para o projeto de banco de dados Turso (Limbo), que abrange as regras de correção, os padrões típicos do Rust e orientações sobre comentários e prevenção de over-engineering que os colaboradores devem seguir sempre que escrevem código. Seu princípio norteador é o fato de se tratar de um banco de dados em produção, onde a correção é primordial e um travamento é preferível à corrupção de dados, por isso ela codifica os hábitos que mantêm o conjunto de códigos seguro.

O guia estabelece regras de correção (sem soluções temporárias ou truques rápidos, use assert com frequência, cause travamento em estados inválidos que possam comprometer a integridade dos dados, leve em conta casos extremos) e padrões do Rust (faça com que estados ilegais não sejam representáveis, utilize correspondência exaustiva de padrões, prefira enums a strings/sentinels, minimize alocações no heap, escreva código otimizado para CPU). Ele oferece orientações concretas sobre instruções if — use assert!, retorne um erro ou unreachable! para ramificações que nunca deveriam ser executadas, em vez de ignorá-las silenciosamente — e regras de comentários que incentivam a documentar o “porquê” em vez do “o quê”, proibindo referências a conversas com IA e marcadores temporais. Também adverte para verificar cuidadosamente a ordem das mutações de índice em relação ao SQLite, a fim de evitar inconsistências, aponta para uma habilidade relacionada ao modelo async I/O e lista regras de limpeza para evitar código morto ou soluções incompatíveis com versões anteriores.

Ele se destina aos colaboradores do conjunto de códigos Rust Turso/Limbo e, de forma mais ampla, a qualquer pessoa que desenvolva em Rust em nível de sistema e deseje um checklist compacto de correção. Trata-se de documentação puramente consultiva — sem scripts, comandos, credenciais ou efeitos colaterais — sendo, portanto, totalmente inofensiva.

Perguntas frequentes

Qual é o princípio fundamental?

Trata-se de um banco de dados em produção, onde a correção é primordial; por isso, um travamento é preferível à corrupção de dados. As regras incentivam que erros sejam detectados claramente, em vez de continuar em um estado indefinido.

Como devo lidar com ramificações que nunca deveriam ocorrer?

Não as ignore silenciosamente. Use assert! com uma mensagem explicativa, retorne um erro ou utilize unreachable! — reserve instruções if/else simples para casos em que ambas as ramificações são caminhos esperados.

Quais são as regras de comentários?

Documente o “porquê” em vez do “o quê”, documente funções/estruturas/enums/variantes e evite comentários que repitam código, façam referências a conversas com IA ou contenham marcadores temporais como “added” ou “Phase 1”.

Ele se aplica além do Turso?

Foi escrito para o conjunto de códigos Rust Turso/Limbo, mas suas orientações sobre correção e padrões do Rust são amplamente úteis para trabalhos em Rust em nível de sistema.

Por que ele destaca as mutações de índice?

Porque a ordem de inserção, exclusão e resolução de conflitos deve corresponder à do SQLite; uma ordem incorreta causa inconsistências nos índices que são fáceis de passar despercebidas.