code-quality

О качестве кода

code-quality — это краткий справочник правил кодирования для проекта базы данных Turso (Limbo), в котором изложены правила корректности, идиомы языка Rust, рекомендации по комментариям и предотвращению чрезмерной сложности кода, которые разработчики должны соблюдать при написании программного обеспечения. Основная идея документа заключается в том, что речь идет о производственной базе данных, где корректность имеет первостепенное значение, и аварийный сбой предпочтительнее повреждения данных; поэтому здесь кодифицируются привычки, обеспечивающие безопасность кодовой базы.

В руководстве описаны правила корректности (отказ от временных решений и быстрых хаков, частое использование функций assert, сброс при некорректном состоянии, угрожающем целостности данных, учет крайних случаев) и паттерны языка Rust (делать недопустимые состояния не представимыми, использовать полное совпадение шаблонов, отдавать предпочтение enum перед строками/сентинелами, минимизировать выделение памяти на куче, писать код, оптимизированный для работы процессора). Приводятся конкретные рекомендации по использованию операторов if — применять assert!, возвращать ошибку или использовать unreachable! для веток, которые никогда не должны выполниться, вместо того чтобы молча игнорировать их, а также правила комментариев, предполагающие описание причин вместо описания самого факта, при этом запрещается использование ссылок на диалоги с ИИ и временных меток. Также указывается на необходимость дважды проверять порядок изменения индексов по отношению к SQLite для избежания несоответствий, упоминается связанная с этим навык работы с асинхронным вводом-выводом, а также перечисляются правила очистки кода от «мертвого» кода или обходных решений, несовместимых со старыми версиями.

Документ предназначен для участников разработки кодовой базы Turso/Limbo на Rust, а также для всех, кто пишет программное обеспечение на Rust на уровне систем и нуждается в компактном чек-листе правил корректности. Это исключительно справочный документ — без скриптов, команд, учетных данных или побочных эффектов, поэтому он полностью безвреден.

Часто задаваемые вопросы

Какова основная идея документа?

Речь идет о производственной базе данных, где корректность имеет первостепенное значение; поэтому аварийный сбой предпочтительнее повреждения данных. Правила побуждают разработчиков явно выявлять ошибки, а не продолжать работу в некорректном состоянии.

Как следует обращаться с ветками кода, которые никогда не должны возникнуть?

Не игнорируйте их молча. Используйте функцию assert! с сообщением о нарушении правил, возвращайте ошибку или используйте unreachable! — обычные конструкции if/else следует оставлять для случаев, когда обе ветки являются возможными путями выполнения.

Каковы правила написания комментариев?

Описывайте причины, а не сам факт, документируйте функции/структуры/enums/variants, избегайте комментариев, которые повторяют код, содержат ссылки на диалоги с ИИ или временные метки вроде «added» или «Phase 1».

Применим ли этот документ за пределами Turso?

Он написан для кодовой базы Turso/Limbo на Rust, но его рекомендации по корректности и идиомам языка Rust в целом полезны при работе с Rust на уровне систем.

Почему в документе упоминаются изменения индексов?

Потому что порядок выполнения операций insert, delete и разрешения конфликтов должен соответствовать стандартам SQLite; неправильный порядок приводит к несоответствиям в индексах, которые легко ускользнуть от внимания.