The pit of Failure (or Success)

Часто при проектировании API кроме того что нам важно думать не только о фичах и возможностях которые он дает, но и какой импакт этот API несет при использовании. И тут есть 2 противоположных концепта: Falling Into The Pit of Success/Failure или при переводе Упасть В Яму Успеха/Неудачи.

Какие же ключевые принципы разработки за этим скрываются? Если сократить и упростить, то выйдет: Делай так чтобы правильно было использовать легко, а неправильно сложно. Те наша задача мотивировать людей и поощрять правильное использование API и делать так, чтобы некорректное использование всем видом кричало, что тут дела обстоят не так (fall into the pit of success). Обратный пример, когда API словно подталкивает использовать себя грязно, а использовать корректно больше похоже на тернистый путь или полосу испытаний (Я думаю каждый сталкивался с таким ощущением)

Давайте возьмем пару примеров из API и рассмотрим их:
React:

<div dangerouslySetInnerHTML={{ __html: "Hello" }} />

И тут нам интересно API dangerouslySetInnerHTML, видите что оно делает? Да, оно всем своим видом кричит, что вы делаете что-то опасное и нехорошее, а громоздкость с { __html: "Hello" } дополняет картинку. В добавок вам еще будет сложнее точно сходу вспомнить правильное написание и вы пойдете в документацию, где вам еще раз дадут понять: "скорее всего ты делаешь что-то не то". Это прекрасный пример того, как с помощью API вам не дают применить нечто потенциально опасное.

И вот сегодня я увидел обратный пример из мира Svelte:

let double = $derived(count*2);
double = 3.14;

Это сегодняшний анонс долгожданной фичи, чтобы вычислимые значения могли быть временно изменены. Крутая же фича? В целом да, ее запрашивали и ждали, а без нее приходилось использовать костыли. И вроде как надо радоваться? Нам же дали возможность и маловероятно, что оно что-то сломает... Но вот тут как раз всплывает тема того к чему мы подталкиваем дизайном нашего API.

В реактивной системе необходимость делать writable вычислимые поля достаточно редка. Кроме того нам дали возможность делать только прямую запись, а не условный сеттер который бы позволил сделать two way connection, нет, это не тот случай! Те мы можем просто лезть в кэш вычислимого свойства и подменять его до изменения значения. Ну надо же людям эту фичу, в чем проблема? А в том, что в 99% случаев эта фича не нужна, а вот все 100% $derived полей стали вместо read-only теперь writable. И никакой вас TypeScript не спасет от записи в него случайно (например, при рефакторинге) и вы больше видя перед собой $derived не можете быть уверены записывают что-то в него или нет, эта информация лежит где-то в другом месте компонента и пока вы не прочтете код компонента полностью вы больше не можете быть в этом уверены.

Таким образом эта возможность не подталкивает к правильному использованию сигналов, делает так что допускать случайные ошибки стало проще и при этом осталось относительно скудным по возможностям (как и написал это не дает возможность делать two way connection). С другой стороны мы покрыли возможность 1% от случаев. Вот это пример, когда мы видим собой pit of failure, да нас не мотивируют прямым образом использовать этот функционал неправильно, но "заборчик" рядом с ямой куда-то унесли.

Как этого можно было избежать?
Использовать отдельный нейминг

let double = $writableDerived(count*2);
double = 3.14;

Или использовать отдельный параметр

let double = $derived(count*2, { writable: true }); // или любая другая явная модификация
double = 3.14;

Или на худой конец если мы хотим оставить магию в нашем мире, то создать явное API

let double = $derived(count*2);
$modifyDerivedCache(double, 3.14); // мы сделали неудобное, но однозначное API

Это все еще лучше, чем выкинуть забор и дать неявное по смыслу API.

Не думайте что это "написать плохо на чем угодно можно" /"вопрос прямых рук". НЕТ! Вы, как автор API, должны формировать у людей прямые руки, а кривые выпрямлять. Пожалуйста, прикидывайте в голове эти сценарии: "мотивирую ли я делать что-то плохое" и "поощряю ли я правильное использование". Спасибо...