Сколько низкоуровневых вещей выставить в API?

Question

При проектировании общедоступного API общей библиотеки, сколько из низкоуровневого материала, который используется внутри, должен быть представлен? С одной стороны, пользователи не должны слишком сильно зависеть от деталей реализации, и слишком много низкоуровневых функций / классов могут загромождать API. Следовательно, ответ коленного рефлекса может быть «нет». С другой стороны, некоторые из низкоуровневых функциональных возможностей могут быть полезны людям, и раскрытие большего их количества может предотвратить инверсию абстракции (повторное внедрение низкоуровневых конструкций поверх высокоуровневых конструкций).

Кроме того, раскрытие более низкоуровневых деталей может обеспечить сокращение производительности. Например, допустим, у вас есть функция для нахождения медианы массива. Принцип наименьшего удивления гласит, что вы должны дублировать массив, чтобы пользователи вашего API не заботились о том, что его реализация связана с побочным эффектом переупорядочения элементов. Следует ли вам в этом случае отметить, что median () стоит выделение памяти и предоставляет другую функцию, которая обходит выделение, но произвольно переупорядочивает ввод пользователя?

Каковы общие рекомендации относительно того, сколько деталей такого рода раскрыть?

Answer 1

Ваш API не должен позволять вызывающим объектам «ломать» что-либо, портя состояние внутренних элементов (например, переупорядочивание коллекций и т. Д.) Чтобы решить эту проблему, ваши открытые интерфейсы должны читаться только при необходимости.

---

Что касается сложности, я склоняюсь далеко в сторону простых, базовых методов. Я очень стараюсь не перегружать себя чем-то, что, по моему мнению, понадобится в будущем.

Пишите в соответствии с требованиями сегодняшнего дня (возможно, завтра), но не более того. Вы всегда можете продлить в будущем. Гораздо сложнее просто бросать вещи, которые ты больше не можешь поддерживать.

Answer 2

Как можно меньше.

Чем больше деталей вы раскрываете, тем больше вероятность, что изменение сломает потребителя.

Answer 3

Один из способов, который я слышал, это выразить: разоблачить что , но не как .

Цель состоит в том, чтобы предоставить клиентам полезную и богатую библиотеку, не делая их зависимыми от внутренних компонентов библиотеки. Вы хотите иметь возможность менять внутренние компоненты, не нарушая абонентов (как уже заметил кто-то другой).

Для написания хорошего API требуется определенное количество искусного владения краем.

Answer 4

Unix способ сделать это - предоставить механизмы, а не политики. Просто предоставьте нужные инструменты для выполнения каких-либо действий (скажем, нож), но старайтесь не предвидеть, как они будут использоваться (для очистки яблок или для заточки карандашей).