code-quality

À propos de la qualité du code

code-quality est une référence concise sur les conventions de codage destinée au projet de base de données Turso (Limbo), qui recense les règles de correction, les idiomes Rust ainsi que des directives relatives aux commentaires et à l’évitation d’une sur-ingénierie que les contributeurs doivent appliquer à chaque fois qu’ils écrivent du code. Son principe directeur est le suivant : il s’agit d’une base de données en production où la correction est primordiale, et un plantage est préférable à une corruption des données ; c’est pourquoi ce document formalise les habitudes qui permettent de maintenir la sécurité du codebase.

Ce guide énonce des règles de correction (interdiction des solutions de fortune ou des astuces rapides, utilisation fréquente d’assertions, plantage en cas d’état invalide pouvant compromettre l’intégrité des données, prise en compte des cas limites) ainsi que des patterns Rust (rendre les états illégaux irreprésentables, utilisation de correspondances exhaustives, préférence aux enums plutôt qu’aux chaînes ou sentinelles, minimisation des allocations sur le heap, écriture de code adapté au CPU). Il propose également des indications concrètes concernant les instructions if : utiliser assert! , retourner une erreur ou unreachable! pour les branches qui ne devraient jamais être atteintes, plutôt que de les ignorer silencieusement — ainsi que des règles de commentaires encourageant la documentation des raisons derrière les actions plutôt que des détails techniques, tout en interdisant les références à des conversations avec des IA et les marques temporelles. Il met également en garde contre la nécessité de vérifier soigneusement l’ordre des mutations d’index par rapport à SQLite afin d’éviter les incohérences, indique une compétence liée au modèle I/O asynchrone pertinent, et énumère des règles de nettoyage visant à éviter la présence de code mort ou de solutions compatibles en arrière-plan.

Il s’adresse aux contributeurs du codebase Rust Turso/Limbo, mais plus généralement à tout développeur travaillant avec Rust au niveau système qui souhaite disposer d’une liste de contrôle concise pour assurer la correction de son code. Il s’agit purement d’une documentation consultative — sans scripts, commandes, identifiants ou effets secondaires — ce qui en fait un document entièrement inoffensif.

FAQ

Quel est le principe fondamental ?

Il s’agit d’une base de données en production où la correction est primordiale ; un plantage est donc préférable à une corruption des données. Les règles encouragent à provoquer un échec visible plutôt que de continuer dans un état indéfini.

Comment dois-je gérer les branches qui ne devraient jamais se produire ?

Ne les ignorez pas silencieusement. Utilisez assert! accompagné d’un message explicatif, retournez une erreur, ou utilisez unreachable! — réservez les simples if/else aux cas où les deux branches représentent des chemins attendus.

Quelles sont les règles de commentaires ?

Documentez les raisons derrière les actions plutôt que les détails techniques, documentez les fonctions, structures, enums et variants, et évitez les commentaires qui répètent du code, font référence à des conversations avec des IA ou contiennent des marques temporelles telles que « ajouté » ou « Phase 1 ».

S’applique-t-il au-delà de Turso ?

Il a été écrit pour le codebase Rust Turso/Limbo, mais ses directives relatives à la correction et aux idiomes Rust sont largement utiles pour tout travail en Rust au niveau système.

Pourquoi met-il l’accent sur les mutations d’index ?

Parce que l’ordre des opérations d’insertion, de suppression et de résolution des conflits doit correspondre à celui de SQLite ; un ordre incorrect entraîne des incohérences dans les index qui sont faciles à manquer.