Перейти до вмісту
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 про порт, із якого почалася ця серія.