Перейти к содержимому
Leonidov.DEV

Перенос библиотеки: 5 правил сохранения совпадения

Инженерия
Перенос библиотеки: 5 правил сохранения совпадения

Вторая реализация это обещание, что две среды отвечают на один вопрос. Большинство портов ломают это обещание в первый месяц, тихо, и ущерб виден как две панели, которые расходятся в числах. Перенос библиотеки это в основном работа по сохранению совпадения, и мне её сделали пять правил.

Код: ReadSightRS, лицензия MIT.

Каноническая реализация написана на PHP. Крейт на Rust это побайтно точный порт, и те же правила применились к версиям на Python и Node.

Правило 1: ответ принадлежит одной реализации

Библиотека на PHP решает, что значит формула. Каждый другой язык её воспроизводит, включая округление и включая крайний случай, когда в тексте нет предложений.

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

Правило кажется очевидным, пока в порте не появляется свой пользователь. Тогда просьба «поправьте у нас» звучит разумно, а ответ «сначала в PHP» требует объяснить, что улучшение в одном языке ломает сравнение между языками.

Правило 2: векторы генерируют, а не пишут

Эталонные векторы приходят из PHP-библиотеки, а не из порта. Они покрывают список поддерживаемых формул на язык, метрики analyze, каждую применимую формулу со своими inputs и повекторные слоги, сравнение с допуском 1e-9.

Написанные руками ожидания проверяют, что думал автор. Сгенерированные векторы проверяют, что делает оригинал, и только это порт обязан повторить.

Правило 3: приблизительность описана на месте применения

Счёт слогов по шаблонам TeX точен в точках переноса и приблизителен в количестве. Это свойство алгоритма, а не дефект, и его место в README рядом с таблицей режимов.

Четыре славянских языка идут на эвристике. Человек, который прочитал таблицу, знает, почему «дыхание» считается как четыре; тот, кто не прочитал, заводит баг, на который мейнтейнер ответил десять раз.

Правило 4: говорить идиомами языка, держать смысл

ReadSight::new() в Rust возвращает Result, score() возвращает Result<FormulaResult, Error>, пустой ввод это Error::EmptyText. Python поднимает исключение с тем же смыслом, JavaScript бросает.

Идиомы меняют форму вызова и никогда не меняют число, которое вернулось. Порт, который отдаёт ноль вместо ошибки, проще написать и опаснее использовать в пакетном прогоне.

Правило 5: исполняемая документация считается тестом

Примеры на Rust в README компилируются и запускаются через cargo test. Девяносто интеграционных тестов покрывают совпадение, перенесённые юнит-тесты и дымовой прогон, который собирает каждый язык и вызывает каждую поддерживаемую формулу.

README, который компилируется, не может разойтись с API. README, который только текст, расходится на первом переименовании, и первым это замечает пользователь, вставивший сломанный пример.

Чему учит третий порт

К третьему языку картина ясна: общая часть это данные и векторы, а каждый порт тонкий вокруг них. Rust вкладывает данные в бинарник, Python кеширует скомпилированные шаблоны в системном каталоге, Node возит их в пакете.

Это и есть полезный итог упражнения. Интересная работа ушла в одну каноническую реализацию и один набор векторов, остальное это адаптация, а адаптация дешева, когда определение правильного не обсуждается.

Где это заканчивается

Совпадение это функция, которую пользователь не видит. Оно держит сравнение двух документов после того, как конвейер под ними переписали, и оно незаметно до того дня, когда его нет.

Крейт выходит под MIT, #![forbid(unsafe_code)], а векторы лежат в репозитории, чтобы четвёртый порт начинался с определения, а не с догадки.

Чек-лист порта проверяйте на каждом шаге: тесты должны падать до правки и проходить после.

Рядом: библиотека читаемости о канонической библиотеке на PHP и читаемость в Node о порте, с которого началась эта серия.