Явные методы API в сравнении с обобщенными методами API, основанными на параметрах

Question

При определении API, доступного для клиента, предпочтительной отраслевой практикой является следующее:

a) Определение набора явных методов API, каждый из которых имеет очень узкое и конкретное назначение, например:

SetUserName    <name>
SetUserAge     <age>
SetUserAddress <address>

b) Определение набора из более обобщенных методов API, основанных на параметрах, например:

SetUserAttribute <attribute>

enum attribute {
    name,
    age,
    address
}

Мое мнение:

В пользу (a)

Для логических методов (например, EnableFoo) я бы определенно предпочел вариант (а), поскольку намерения намного более ясны, в будущем для него менее вероятно потребуются расширения, и он сделает более читабельный код.

Например, метод с именем EnableDisableFoo, который принимает логический параметр, указывающий, следует ли включать или отключать, не очень понятен и не имеет связной цели.

Когда есть несколько вариантов, проблема усложняется.

В пользу (b)

Опция (b) - отличный способ обеспечить расширяемость в API, но за счет удобства использования. С опцией (a) само имя метода API дает достаточно информации, чтобы указать, что он делает. С опцией (b) пользователь должен найти и имя метода и соответствующее перечисление / параметр для использования. Теоретически это делает вариант (b) хуже с точки зрения удобства использования - но, возможно, использование меньшего количества методов - это хорошо, поэтому даже это не совсем верно.

Другие мысли

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

У кого-нибудь есть мысли по этому поводу?

Answer 1

Я бы лично высказался за (а), поскольку наша цель - сделать «статический» код максимально точным и надежным.

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

Это очень похоже на аргумент для определения и использования перечислений или явных типов, а не использования и возврата целых чисел в старом стиле C, поскольку вы получаете еще один уровень уверенности.

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

Answer 2

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

Answer 3

Я думаю, это зависит от кода, который вы пишете. Если вы пишете о вещах, которые всегда сочетаются друг с другом (т. Е. Если вы собираетесь использовать / менять возраст всегда с именем), тогда переходите к пункту b, в противном случае - хорошо.

Но не пытайтесь переусердствовать (а), потому что тогда вы просто напишите намного больше строк и сделаете намного меньше. Хорошая идея, если вам платят за количество написанного вами кода:)